28
edits
Changes
From Gramps
Synced from repo@41d611f via publish.py
<!--
Curated reference. Two principles:
1. Anything an addon may import lives under gramps.gen.*. gen is
self-contained (cannot import from gui / plugins) — see
AGENTS.md "Submodule Import Rules".
2. This page is a NAVIGATOR. For exhaustive signatures, read the
source of the module referenced (or the upstream Sphinx docs).
Adding signatures here would have us chasing version drift.
Scraped sources:
- report-api.md (93L) — TextDoc / DrawDoc / GVDoc structure trees
- report-generation.md (88L) — Text / Draw / Graphviz / Web categorisation
-->
== Overview ==
The curated <code>gramps.gen.*</code> surface addons are allowed to import. <code>gen</code> is the self-contained core submodule (it must not import from <code>gui</code> or <code>plugins</code>); importing only from <code>gen</code> keeps an addon portable across UI variants and testable without a display.
This page is a navigator, not a generated API dump. For exhaustive signatures, read the source of the module referenced — the [https://gramps-project.org/docs/ upstream Sphinx docs] carry the same information formatted for browsing.
== Allowed surface ==
=== Database ===
{|
! Module / class
! Notes
|-
| <code>gramps.gen.db.base.DbReadBase</code>
| Read-only DB interface — what addon code typically receives
|-
| <code>gramps.gen.db.base.DbWriteBase</code>
| Mutation interface; reach via <code>db</code> after <code>with DbTxn(...) as trans</code>
|-
| <code>gramps.gen.db.txn.DbTxn</code>
| Transaction context manager — required for every write
|-
| <code>gramps.gen.db.utils.open_database</code>
| Open a tree by path; used in repro scripts and tests
|-
| <code>gramps.gen.db.exceptions</code>
| DB-layer exception hierarchy
|}
See [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Data_access|06-data-access]] for the addon-facing patterns that use this surface.
=== Object model ===
{|
! Module
! Notes
|-
| <code>gramps.gen.lib</code>
| Every primary class: <code>Person</code>, <code>Family</code>, <code>Event</code>, <code>Place</code>, <code>Source</code>, <code>Citation</code>, <code>Repository</code>, <code>Media</code>, <code>Note</code>, <code>Tag</code>. Plus value classes (<code>Name</code>, <code>Date</code>, <code>Address</code>, <code>Surname</code>, <code>EventRef</code>, …).
|-
| <code>gramps.gen.lib.person.Person</code>
| The gender constants (<code>Person.MALE</code>, <code>Person.FEMALE</code>, <code>Person.UNKNOWN</code>) are class attributes
|}
The full inventory is large; the cheapest reference is the source under [https://github.com/gramps-project/gramps/tree/maintenance/gramps60/gramps/gen/lib <code>gramps/gen/lib/</code>]. Every primary class has matching <code>get_*</code> / <code>set_*</code> accessors; relationships are exposed as handle lists (<code>get_family_handle_list</code>) or ref lists (<code>get_event_ref_list</code>, <code>get_child_ref_list</code>).
=== Types and IDs ===
{|
! Module
! Notes
|-
| <code>gramps.gen.types</code>
| <code>PersonHandle</code>, <code>FamilyHandle</code>, …, <code>PersonGrampsID</code>, <code>FamilyGrampsID</code>, …
|}
Prefer these over bare <code>str</code> in addon code that handles either kind of identifier. It documents intent for the next reader and makes mistakes (handle vs ID) catchable with <code>mypy</code>. See [16-guidelines → Coding styleN-guidelines.md#coding-style).
=== Errors ===
{|
! Module
! Use
|-
| <code>gramps.gen.errors</code>
| Raise existing exceptions here before inventing new classes
|-
| <code>gramps.gen.errors.HandleError</code>
| Invalid or missing handles
|-
| <code>gramps.gen.db.exceptions</code>
| DB-layer-specific exceptions
|}
=== Plugin base classes ===
{|
! Class / module
! Used by
|-
| <code>gramps.gen.plug.Gramplet</code>
| <code>GRAMPLET</code> addons
|-
| <code>gramps.gen.plug.report.Report</code>
| <code>REPORT</code> addons
|-
| <code>gramps.gen.plug.report.MenuReportOptions</code>
| Options form for report addons
|-
| <code>gramps.gen.plug.report.stdoptions</code>
| Pre-built options like locale chooser
|-
| <code>gramps.gen.plug.docgen.BaseDoc</code>
| <code>DOCGEN</code> addons (base)
|-
| <code>gramps.gen.plug.docgen.TextDoc</code>
| Text reports
|-
| <code>gramps.gen.plug.docgen.DrawDoc</code>
| Graphical (drawing) reports
|-
| <code>gramps.gen.plug.docgen.GVDoc</code>
| Graphviz-based reports
|-
| <code>gramps.gen.plug.docgen.FontStyle</code>, <code>ParagraphStyle</code>
| Style definitions for text reports
|-
| <code>gramps.gen.plug.docgen.PaperStyle</code>, <code>PaperSize</code>
| Page geometry for graphical reports
|-
| <code>gramps.gen.plug.menu</code>
| Options-form widgets
|-
| <code>gramps.gen.filters.rules.Rule</code> (and namespace bases)
| <code>RULE</code> addons
|-
| <code>gramps.gen.simple.SimpleAccess</code>, <code>SimpleDoc</code>
| Quick Views
|}
Most <code>gramps.gui.*</code> classes are ''internal''; addons that import from there will break across Gramps versions. The exceptions used in this manual's tutorials — <code>gramps.gui.plug.tool.Tool</code>, <code>gramps.gui.plug.quick.QuickTable</code>, <code>gramps.gui.dialog.OkDialog</code> — are documented because every existing Tool / Quick View in core uses them, but they are nevertheless GUI-coupled. Pure logic factored out into modules that import only from <code>gen</code> stays unit-testable without a display.
=== Report categories ===
For <code>REPORT</code> addons, register with one of these category constants (see [https://github.com/gramps-project/gramps/blob/maintenance/gramps60/gramps/gen/plug/_pluginreg.py <code>_pluginreg.py:141-149</code>]):
{|
! Category
! Docgen interface
! Notes
|-
| <code>CATEGORY_TEXT</code>
| <code>TextDoc</code>
| Text reports — PDF, HTML, ODF, plain text
|-
| <code>CATEGORY_DRAW</code>
| <code>DrawDoc</code>
| Graphical reports drawn at exact coordinates
|-
| <code>CATEGORY_GRAPHVIZ</code>
| <code>GVDoc</code>
| Graphviz / DOT input — laid out by graphviz
|-
| <code>CATEGORY_WEB</code>
| (direct file I/O)
| Narrative website — writes HTML/CSS directly to files
|-
| <code>CATEGORY_BOOK</code>
| <code>TextDoc</code> + <code>DrawDoc</code>
| A composition of Text and Draw reports
|-
| <code>CATEGORY_TREE</code>
| <code>DrawDoc</code>
| Genealogical tree-chart layouts
|-
| <code>CATEGORY_CODE</code>
| (none)
| Catch-all for reports that don't fit elsewhere
|}
Only <code>CATEGORY_TEXT</code> and <code>CATEGORY_DRAW</code> participate in <code>CATEGORY_BOOK</code>.
=== Document API: structure at a glance ===
The three docgen interfaces have distinct hierarchies. Knowing which container nests what saves a long trip through the source.
'''<code>TextDoc</code> — sequential text layout, paginated by the backend.'''
<pre>Document
├── Paragraph
├── Pagebreak
├── Table
│ └── Row
│ └── Cell
│ ├── Paragraph
│ └── Image
└── Image</pre>
Paragraph styles drive titles, body text, list entries. The backend or external viewer handles pagination, except where a manual <code>Pagebreak</code> is inserted. Index marks attach to text within a paragraph (<code>gramps.gen.plug.docgen.IndexMark</code>), feeding the table of contents in Book reports.
'''<code>DrawDoc</code> — exact-coordinate graphics on a frame.'''
<pre>Document
└── Frame
├── Line
├── Polygon
├── Box
└── Text</pre>
The frame is the drawing surface; elements get placed by coordinates supplied by the report. The origin is the top-left of the usable area (page minus margins). Graphical reports need to honour <code>PaperStyle.get_usable_width()</code> / <code>…_height()</code> — drawing into the margins is a contract violation.
'''<code>GVDoc</code> — graphviz model.'''
<pre>Document
└── Subgraph
├── Node
├── Link
└── Comment</pre>
The report defines nodes, links, and comments; layout is the external graphviz binary's job. This is why <code>requires_exe=["dot"]</code> appears on Graphviz-based addons.
=== Paper geometry (Draw / Tree only) ===
<code>gramps.gen.plug.docgen.PaperStyle</code> holds:
* the paper size (a <code>PaperSize</code> instance),
* margins,
* orientation (portrait / landscape).
Convenience accessors <code>get_usable_width()</code> and <code>get_usable_height()</code> return the drawing-area dimensions (paper size minus margins, in orientation order — width is always horizontal). Text reports don't need to read these; the backend paginates around them.
=== Locale and translation ===
{|
! Module / class
! Use
|-
| <code>gramps.gen.const.GRAMPS_LOCALE</code> (alias <code>glocale</code>)
| The live locale; entry point for <code>_()</code> injection
|-
| <code>glocale.get_addon_translator(__file__).gettext</code>
| Bind <code>_</code> to the addon's own <code>po/</code> catalog
|-
| <code>gramps.gen.utils.grampslocale.GrampsLocale</code>
| Instantiate directly to pin a locale in repro scripts
|-
| <code>glocale.translation.ngettext</code>
| Plural-aware translation
|-
| <code>glocale.translation.sgettext</code>
| Strip translator-hint prefix; used with `"hint
|}
See [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Fundamentals#translation|05-fundamentals → Translation]] for the addon-side opt-in, and [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Debug#reproduction-scripts-that-bypass-the-gui|09-debug → Reproduction scripts that bypass the GUI]] for the <code>GrampsLocale(localedir, languages)</code> pattern in repros.
=== Filters and selection ===
{|
! Module / class
! Use
|-
| <code>gramps.gen.filters.GenericFilterFactory</code>
| Construct a filter for a namespace
|-
| <code>gramps.gen.filters.rules</code>
| The rule catalogue (one subpackage per namespace)
|-
| <code>gramps.gen.filters.rules.<namespace>.Rule</code>
| Base class to subclass when writing a custom rule (see [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-custom-filter-rule|03-tutorials]])
|}
The modern rule entry point is <code>apply_to_one(db, obj)</code> (see [https://github.com/gramps-project/gramps/blob/maintenance/gramps60/gramps/gen/filters/rules/_rule.py#L162 <code>_rule.py:162</code>]). Older code used <code>apply()</code>.
=== Logging ===
{|
! Module / class
! Use
|-
| <code>logging.getLogger(__name__)</code>
| Module-level logger; see [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Fundamentals#logging|05-fundamentals → Logging]]
|}
There's nothing addon-specific to import here; addons use stdlib <code>logging</code> exactly like Gramps' own modules do.
=== Simple Access (Quick Views) ===
{|
! Class
! Use
|-
| <code>gramps.gen.simple.SimpleAccess</code>
| High-level DB read interface — hides handles and refs
|-
| <code>gramps.gen.simple.SimpleDoc</code>
| Matching write interface — <code>title</code>, <code>paragraph</code>, <code>header1</code>, …
|-
| <code>gramps.gui.plug.quick.QuickTable</code>
| Clickable result table (GUI-coupled; QuickView-only)
|}
See [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-quick-view|03-tutorials → A Quick View]] for the standard pattern.
== What's NOT API ==
Anything under <code>gramps.gui.*</code> or <code>gramps.plugins.*</code> is internal to the shipped distribution; addons that import from there break across Gramps versions. The exceptions (Tool / Quick View / Dialog) are documented above and unavoidable for those addon kinds, but pure logic should be factored out behind a <code>gen.*</code>-only boundary so it stays unit-testable without a display.
If you find yourself reaching into <code>gramps.gui.*</code> or <code>gramps.plugins.*</code> for something that ''isn't'' tied to GUI display, the right move is usually to ask upstream to promote what you need into <code>gen</code>. The [https://www.gramps-project.org/wiki/index.php/Committing_policies committing policies wiki page] and the gramps-devel mailing list are the channels.
== See also ==
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Addon_Kinds|04-addon-kinds]] — which kinds use which base classes.
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Fundamentals|05-fundamentals]] — the cross-cutting concepts (logging, translation, signals) backed by this surface.
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Data_access|06-data-access]] — patterns over the DB API.
* [[Report_API|13-compatibilityL-compatibility.md) — what changes across Gramps versions in this surface.
- [Report API]], [[Report_Generation|Report Generation]] — standalone wiki references for the docgen subsystem.
* [[Simple_Access_API|Simple Access API]] — the standalone wiki page for <code>SimpleAccess</code> / <code>SimpleDoc</code>.
* [https://gramps-project.org/docs/ Gramps Developer Reference] — upstream Sphinx-generated API docs.
{{stub}}
Curated reference. Two principles:
1. Anything an addon may import lives under gramps.gen.*. gen is
self-contained (cannot import from gui / plugins) — see
AGENTS.md "Submodule Import Rules".
2. This page is a NAVIGATOR. For exhaustive signatures, read the
source of the module referenced (or the upstream Sphinx docs).
Adding signatures here would have us chasing version drift.
Scraped sources:
- report-api.md (93L) — TextDoc / DrawDoc / GVDoc structure trees
- report-generation.md (88L) — Text / Draw / Graphviz / Web categorisation
-->
== Overview ==
The curated <code>gramps.gen.*</code> surface addons are allowed to import. <code>gen</code> is the self-contained core submodule (it must not import from <code>gui</code> or <code>plugins</code>); importing only from <code>gen</code> keeps an addon portable across UI variants and testable without a display.
This page is a navigator, not a generated API dump. For exhaustive signatures, read the source of the module referenced — the [https://gramps-project.org/docs/ upstream Sphinx docs] carry the same information formatted for browsing.
== Allowed surface ==
=== Database ===
{|
! Module / class
! Notes
|-
| <code>gramps.gen.db.base.DbReadBase</code>
| Read-only DB interface — what addon code typically receives
|-
| <code>gramps.gen.db.base.DbWriteBase</code>
| Mutation interface; reach via <code>db</code> after <code>with DbTxn(...) as trans</code>
|-
| <code>gramps.gen.db.txn.DbTxn</code>
| Transaction context manager — required for every write
|-
| <code>gramps.gen.db.utils.open_database</code>
| Open a tree by path; used in repro scripts and tests
|-
| <code>gramps.gen.db.exceptions</code>
| DB-layer exception hierarchy
|}
See [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Data_access|06-data-access]] for the addon-facing patterns that use this surface.
=== Object model ===
{|
! Module
! Notes
|-
| <code>gramps.gen.lib</code>
| Every primary class: <code>Person</code>, <code>Family</code>, <code>Event</code>, <code>Place</code>, <code>Source</code>, <code>Citation</code>, <code>Repository</code>, <code>Media</code>, <code>Note</code>, <code>Tag</code>. Plus value classes (<code>Name</code>, <code>Date</code>, <code>Address</code>, <code>Surname</code>, <code>EventRef</code>, …).
|-
| <code>gramps.gen.lib.person.Person</code>
| The gender constants (<code>Person.MALE</code>, <code>Person.FEMALE</code>, <code>Person.UNKNOWN</code>) are class attributes
|}
The full inventory is large; the cheapest reference is the source under [https://github.com/gramps-project/gramps/tree/maintenance/gramps60/gramps/gen/lib <code>gramps/gen/lib/</code>]. Every primary class has matching <code>get_*</code> / <code>set_*</code> accessors; relationships are exposed as handle lists (<code>get_family_handle_list</code>) or ref lists (<code>get_event_ref_list</code>, <code>get_child_ref_list</code>).
=== Types and IDs ===
{|
! Module
! Notes
|-
| <code>gramps.gen.types</code>
| <code>PersonHandle</code>, <code>FamilyHandle</code>, …, <code>PersonGrampsID</code>, <code>FamilyGrampsID</code>, …
|}
Prefer these over bare <code>str</code> in addon code that handles either kind of identifier. It documents intent for the next reader and makes mistakes (handle vs ID) catchable with <code>mypy</code>. See [16-guidelines → Coding styleN-guidelines.md#coding-style).
=== Errors ===
{|
! Module
! Use
|-
| <code>gramps.gen.errors</code>
| Raise existing exceptions here before inventing new classes
|-
| <code>gramps.gen.errors.HandleError</code>
| Invalid or missing handles
|-
| <code>gramps.gen.db.exceptions</code>
| DB-layer-specific exceptions
|}
=== Plugin base classes ===
{|
! Class / module
! Used by
|-
| <code>gramps.gen.plug.Gramplet</code>
| <code>GRAMPLET</code> addons
|-
| <code>gramps.gen.plug.report.Report</code>
| <code>REPORT</code> addons
|-
| <code>gramps.gen.plug.report.MenuReportOptions</code>
| Options form for report addons
|-
| <code>gramps.gen.plug.report.stdoptions</code>
| Pre-built options like locale chooser
|-
| <code>gramps.gen.plug.docgen.BaseDoc</code>
| <code>DOCGEN</code> addons (base)
|-
| <code>gramps.gen.plug.docgen.TextDoc</code>
| Text reports
|-
| <code>gramps.gen.plug.docgen.DrawDoc</code>
| Graphical (drawing) reports
|-
| <code>gramps.gen.plug.docgen.GVDoc</code>
| Graphviz-based reports
|-
| <code>gramps.gen.plug.docgen.FontStyle</code>, <code>ParagraphStyle</code>
| Style definitions for text reports
|-
| <code>gramps.gen.plug.docgen.PaperStyle</code>, <code>PaperSize</code>
| Page geometry for graphical reports
|-
| <code>gramps.gen.plug.menu</code>
| Options-form widgets
|-
| <code>gramps.gen.filters.rules.Rule</code> (and namespace bases)
| <code>RULE</code> addons
|-
| <code>gramps.gen.simple.SimpleAccess</code>, <code>SimpleDoc</code>
| Quick Views
|}
Most <code>gramps.gui.*</code> classes are ''internal''; addons that import from there will break across Gramps versions. The exceptions used in this manual's tutorials — <code>gramps.gui.plug.tool.Tool</code>, <code>gramps.gui.plug.quick.QuickTable</code>, <code>gramps.gui.dialog.OkDialog</code> — are documented because every existing Tool / Quick View in core uses them, but they are nevertheless GUI-coupled. Pure logic factored out into modules that import only from <code>gen</code> stays unit-testable without a display.
=== Report categories ===
For <code>REPORT</code> addons, register with one of these category constants (see [https://github.com/gramps-project/gramps/blob/maintenance/gramps60/gramps/gen/plug/_pluginreg.py <code>_pluginreg.py:141-149</code>]):
{|
! Category
! Docgen interface
! Notes
|-
| <code>CATEGORY_TEXT</code>
| <code>TextDoc</code>
| Text reports — PDF, HTML, ODF, plain text
|-
| <code>CATEGORY_DRAW</code>
| <code>DrawDoc</code>
| Graphical reports drawn at exact coordinates
|-
| <code>CATEGORY_GRAPHVIZ</code>
| <code>GVDoc</code>
| Graphviz / DOT input — laid out by graphviz
|-
| <code>CATEGORY_WEB</code>
| (direct file I/O)
| Narrative website — writes HTML/CSS directly to files
|-
| <code>CATEGORY_BOOK</code>
| <code>TextDoc</code> + <code>DrawDoc</code>
| A composition of Text and Draw reports
|-
| <code>CATEGORY_TREE</code>
| <code>DrawDoc</code>
| Genealogical tree-chart layouts
|-
| <code>CATEGORY_CODE</code>
| (none)
| Catch-all for reports that don't fit elsewhere
|}
Only <code>CATEGORY_TEXT</code> and <code>CATEGORY_DRAW</code> participate in <code>CATEGORY_BOOK</code>.
=== Document API: structure at a glance ===
The three docgen interfaces have distinct hierarchies. Knowing which container nests what saves a long trip through the source.
'''<code>TextDoc</code> — sequential text layout, paginated by the backend.'''
<pre>Document
├── Paragraph
├── Pagebreak
├── Table
│ └── Row
│ └── Cell
│ ├── Paragraph
│ └── Image
└── Image</pre>
Paragraph styles drive titles, body text, list entries. The backend or external viewer handles pagination, except where a manual <code>Pagebreak</code> is inserted. Index marks attach to text within a paragraph (<code>gramps.gen.plug.docgen.IndexMark</code>), feeding the table of contents in Book reports.
'''<code>DrawDoc</code> — exact-coordinate graphics on a frame.'''
<pre>Document
└── Frame
├── Line
├── Polygon
├── Box
└── Text</pre>
The frame is the drawing surface; elements get placed by coordinates supplied by the report. The origin is the top-left of the usable area (page minus margins). Graphical reports need to honour <code>PaperStyle.get_usable_width()</code> / <code>…_height()</code> — drawing into the margins is a contract violation.
'''<code>GVDoc</code> — graphviz model.'''
<pre>Document
└── Subgraph
├── Node
├── Link
└── Comment</pre>
The report defines nodes, links, and comments; layout is the external graphviz binary's job. This is why <code>requires_exe=["dot"]</code> appears on Graphviz-based addons.
=== Paper geometry (Draw / Tree only) ===
<code>gramps.gen.plug.docgen.PaperStyle</code> holds:
* the paper size (a <code>PaperSize</code> instance),
* margins,
* orientation (portrait / landscape).
Convenience accessors <code>get_usable_width()</code> and <code>get_usable_height()</code> return the drawing-area dimensions (paper size minus margins, in orientation order — width is always horizontal). Text reports don't need to read these; the backend paginates around them.
=== Locale and translation ===
{|
! Module / class
! Use
|-
| <code>gramps.gen.const.GRAMPS_LOCALE</code> (alias <code>glocale</code>)
| The live locale; entry point for <code>_()</code> injection
|-
| <code>glocale.get_addon_translator(__file__).gettext</code>
| Bind <code>_</code> to the addon's own <code>po/</code> catalog
|-
| <code>gramps.gen.utils.grampslocale.GrampsLocale</code>
| Instantiate directly to pin a locale in repro scripts
|-
| <code>glocale.translation.ngettext</code>
| Plural-aware translation
|-
| <code>glocale.translation.sgettext</code>
| Strip translator-hint prefix; used with `"hint
|}
See [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Fundamentals#translation|05-fundamentals → Translation]] for the addon-side opt-in, and [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Debug#reproduction-scripts-that-bypass-the-gui|09-debug → Reproduction scripts that bypass the GUI]] for the <code>GrampsLocale(localedir, languages)</code> pattern in repros.
=== Filters and selection ===
{|
! Module / class
! Use
|-
| <code>gramps.gen.filters.GenericFilterFactory</code>
| Construct a filter for a namespace
|-
| <code>gramps.gen.filters.rules</code>
| The rule catalogue (one subpackage per namespace)
|-
| <code>gramps.gen.filters.rules.<namespace>.Rule</code>
| Base class to subclass when writing a custom rule (see [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-custom-filter-rule|03-tutorials]])
|}
The modern rule entry point is <code>apply_to_one(db, obj)</code> (see [https://github.com/gramps-project/gramps/blob/maintenance/gramps60/gramps/gen/filters/rules/_rule.py#L162 <code>_rule.py:162</code>]). Older code used <code>apply()</code>.
=== Logging ===
{|
! Module / class
! Use
|-
| <code>logging.getLogger(__name__)</code>
| Module-level logger; see [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Fundamentals#logging|05-fundamentals → Logging]]
|}
There's nothing addon-specific to import here; addons use stdlib <code>logging</code> exactly like Gramps' own modules do.
=== Simple Access (Quick Views) ===
{|
! Class
! Use
|-
| <code>gramps.gen.simple.SimpleAccess</code>
| High-level DB read interface — hides handles and refs
|-
| <code>gramps.gen.simple.SimpleDoc</code>
| Matching write interface — <code>title</code>, <code>paragraph</code>, <code>header1</code>, …
|-
| <code>gramps.gui.plug.quick.QuickTable</code>
| Clickable result table (GUI-coupled; QuickView-only)
|}
See [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-quick-view|03-tutorials → A Quick View]] for the standard pattern.
== What's NOT API ==
Anything under <code>gramps.gui.*</code> or <code>gramps.plugins.*</code> is internal to the shipped distribution; addons that import from there break across Gramps versions. The exceptions (Tool / Quick View / Dialog) are documented above and unavoidable for those addon kinds, but pure logic should be factored out behind a <code>gen.*</code>-only boundary so it stays unit-testable without a display.
If you find yourself reaching into <code>gramps.gui.*</code> or <code>gramps.plugins.*</code> for something that ''isn't'' tied to GUI display, the right move is usually to ask upstream to promote what you need into <code>gen</code>. The [https://www.gramps-project.org/wiki/index.php/Committing_policies committing policies wiki page] and the gramps-devel mailing list are the channels.
== See also ==
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Addon_Kinds|04-addon-kinds]] — which kinds use which base classes.
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Fundamentals|05-fundamentals]] — the cross-cutting concepts (logging, translation, signals) backed by this surface.
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Data_access|06-data-access]] — patterns over the DB API.
* [[Report_API|13-compatibilityL-compatibility.md) — what changes across Gramps versions in this surface.
- [Report API]], [[Report_Generation|Report Generation]] — standalone wiki references for the docgen subsystem.
* [[Simple_Access_API|Simple Access API]] — the standalone wiki page for <code>SimpleAccess</code> / <code>SimpleDoc</code>.
* [https://gramps-project.org/docs/ Gramps Developer Reference] — upstream Sphinx-generated API docs.
{{stub}}
