Skip to content

Plugin Interfaces

Abstract base classes for extending crategraph. Implement these to add support for new data formats, visualisation engines, or validation rules.

Reader

crategraph.core.interfaces.Reader

Bases: ABC

Base class for graph readers (e.g. RO-Crate, GEXF).

Source code in crategraph/core/interfaces.py 
14
15
16
17
18
19
20
21
22
23
class Reader(ABC):
    """Base class for graph readers (e.g. RO-Crate, GEXF)."""

    @abstractmethod
    def can_read(self, path: str) -> bool:
        """Return True if this reader can handle the given path."""

    @abstractmethod
    def read(self, path: str) -> Graph:
        """Read the source at *path* and return a populated Graph."""

can_read(path) abstractmethod

Return True if this reader can handle the given path.

Source code in crategraph/core/interfaces.py 
17
18
19
@abstractmethod
def can_read(self, path: str) -> bool:
    """Return True if this reader can handle the given path."""

read(path) abstractmethod

Read the source at path and return a populated Graph.

Source code in crategraph/core/interfaces.py 
21
22
23
@abstractmethod
def read(self, path: str) -> Graph:
    """Read the source at *path* and return a populated Graph."""

Writer

crategraph.core.interfaces.Writer

Bases: ABC

Base class for graph writers (e.g. JSON-LD, GEXF).

Source code in crategraph/core/interfaces.py 
26
27
28
29
30
31
32
33
34
35
class Writer(ABC):
    """Base class for graph writers (e.g. JSON-LD, GEXF)."""

    @abstractmethod
    def can_write(self, path: str) -> bool:
        """Return True if this writer can handle the given path."""

    @abstractmethod
    def write(self, graph: Graph, path: str, **kwargs: Any) -> None:
        """Write *graph* to the file at *path*."""

can_write(path) abstractmethod

Return True if this writer can handle the given path.

Source code in crategraph/core/interfaces.py 
29
30
31
@abstractmethod
def can_write(self, path: str) -> bool:
    """Return True if this writer can handle the given path."""

write(graph, path, **kwargs) abstractmethod

Write graph to the file at path.

Source code in crategraph/core/interfaces.py 
33
34
35
@abstractmethod
def write(self, graph: Graph, path: str, **kwargs: Any) -> None:
    """Write *graph* to the file at *path*."""

Renderer

crategraph.core.interfaces.Renderer

Bases: ABC

Base class for graph renderers (visualisation backends).

Concrete renderers should support these common parameters where applicable:

  • colour_by: How to assign node colours (e.g. "type", "community").
  • size_by: How to scale node sizes (e.g. "connections").
  • edge_width: Per-edge width. None = renderer default; int/float = literal pixel width for every edge; str = property name, width-encoded via 1 + 2*log1p(v).
  • filepath: Save output to a file path instead of returning an in-memory object.
  • height / width: Canvas dimensions.

Renderer-specific parameters can be accepted via **kwargs.

Source code in crategraph/core/interfaces.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
class Renderer(ABC):
    """Base class for graph renderers (visualisation backends).

    Concrete renderers should support these common parameters where
    applicable:

    - ``colour_by``: How to assign node colours (e.g. ``"type"``,
      ``"community"``).
    - ``size_by``: How to scale node sizes (e.g. ``"connections"``).
    - ``edge_width``: Per-edge width. ``None`` = renderer default;
      ``int``/``float`` = literal pixel width for every edge;
      ``str`` = property name, width-encoded via ``1 + 2*log1p(v)``.
    - ``filepath``: Save output to a file path instead of returning an
      in-memory object.
    - ``height`` / ``width``: Canvas dimensions.

    Renderer-specific parameters can be accepted via ``**kwargs``.
    """

    @abstractmethod
    def render(self, graph: Graph, **kwargs: Any) -> Any:
        """Render *graph* and return the result."""

render(graph, **kwargs) abstractmethod

Render graph and return the result.

Source code in crategraph/core/interfaces.py 
65
66
67
@abstractmethod
def render(self, graph: Graph, **kwargs: Any) -> Any:
    """Render *graph* and return the result."""

Validator

crategraph.core.interfaces.Validator

Bases: ABC

Base class for graph validators (data quality checks).

Source code in crategraph/core/interfaces.py 
38
39
40
41
42
43
class Validator(ABC):
    """Base class for graph validators (data quality checks)."""

    @abstractmethod
    def validate(self, graph: Graph) -> ValidationReport:
        """Validate *graph* and return a report of issues found."""

validate(graph) abstractmethod

Validate graph and return a report of issues found.

Source code in crategraph/core/interfaces.py 
41
42
43
@abstractmethod
def validate(self, graph: Graph) -> ValidationReport:
    """Validate *graph* and return a report of issues found."""

Inspector

crategraph.core.interfaces.Inspector

Bases: ABC

Base class for file inspectors.

Concrete inspectors examine data files referenced by entities and return structured information about them.

Source code in crategraph/core/interfaces.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
class Inspector(ABC):
    """Base class for file inspectors.

    Concrete inspectors examine data files referenced by entities and
    return structured information about them.
    """

    @abstractmethod
    def supports(self, path: Path) -> bool:
        """Return True if this inspector can handle the resolved file path."""

    @abstractmethod
    def inspect(self, path: Path) -> FileInfo:
        """Inspect the file at *path* and return structured info."""

inspect(path) abstractmethod

Inspect the file at path and return structured info.

Source code in crategraph/core/interfaces.py 
81
82
83
@abstractmethod
def inspect(self, path: Path) -> FileInfo:
    """Inspect the file at *path* and return structured info."""

supports(path) abstractmethod

Return True if this inspector can handle the resolved file path.

Source code in crategraph/core/interfaces.py 
77
78
79
@abstractmethod
def supports(self, path: Path) -> bool:
    """Return True if this inspector can handle the resolved file path."""

Viewer

crategraph.core.interfaces.Viewer

Bases: ABC

Base class for file viewers.

Concrete viewers produce rich HTML previews of data files referenced by entities — images displayed as images, CSVs as interactive tables, audio with playback controls.

Source code in crategraph/core/interfaces.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
class Viewer(ABC):
    """Base class for file viewers.

    Concrete viewers produce rich HTML previews of data files
    referenced by entities — images displayed as images, CSVs as
    interactive tables, audio with playback controls.
    """

    @abstractmethod
    def supports(self, path: Path) -> bool:
        """Return True if this viewer can handle the resolved file path."""

    @abstractmethod
    def view(self, path: Path) -> ViewInfo:
        """View the file at *path* and return a rich HTML preview.

        Implementers must HTML-escape all content derived from file data
        or entity properties before embedding it in the returned
        ``ViewInfo.html``.
        """

supports(path) abstractmethod

Return True if this viewer can handle the resolved file path.

Source code in crategraph/core/interfaces.py 
94
95
96
@abstractmethod
def supports(self, path: Path) -> bool:
    """Return True if this viewer can handle the resolved file path."""

view(path) abstractmethod

View the file at path and return a rich HTML preview.

Implementers must HTML-escape all content derived from file data or entity properties before embedding it in the returned ViewInfo.html.

Source code in crategraph/core/interfaces.py 
 98
 99
100
101
102
103
104
105
@abstractmethod
def view(self, path: Path) -> ViewInfo:
    """View the file at *path* and return a rich HTML preview.

    Implementers must HTML-escape all content derived from file data
    or entity properties before embedding it in the returned
    ``ViewInfo.html``.
    """