Skip to content

Using references

trudag can be used to Reference any data that can be consistently hashed. trudag natively supports References to two sources of data: files in the git tree and files in a remote repository hosted in gitlab.

The included sources can be easily extended using the BaseReference interface. We illustrate this with an example: Referencing content at a specific url, using the frontmatter syntax below.

---
normative: true
level: 1.0
references:
- type: webpage
  url: gitlab.com
---

Deriving a custom reference type from BaseReference

We begin by defining a subclass of BaseReference, WebReference that has type() webpage.

from trudag.dotstop.core.reference.references import BaseReference

class WebReference(BaseReference)
  @classmethod
  def type(cls):
    return "webpage"

Next, lets add a constructor that matches the keywords used in the frontmatter. Also, lets use that url to fetch the relevant content (note this is an example; naively hashing all of the html at some url is not a great plan).

import requests
from trudag.dotstop.core.reference.references import BaseReference

class WebReference(BaseReference)
  def __init__(self, url: str) -> None:
    self.url = url

  @classmethod
  def type(cls) -> str:
    return "webpage"

  @property
  def content(self) -> bytes:
    response = requests.get("https://" + self.url)
    return response.text.encode()

Finally, lets add a summary as valid markdown. For simplicity, we will just use the url itself.

import requests
from trudag.dotstop.core.reference.references import BaseReference

class WebReference(BaseReference)
  def __init__(self, url: str) -> None:
    self._url = url

  @classmethod
  def type(cls) -> str:
    return "webpage"

  @property
  def content(self) -> bytes:
    response = requests.get("https://" + self._url)
    return response.text.encode()

  def as_markdown(self, filepath: None | str = None) -> str:
    return f"`{self._url}`"

Now we have defined our new reference type, we need to make it available to trudag. There are two ways do this: using the local extensions system, or a packaged plugin. Using packaged plugins is recommended for production. The local extensions system is intended for prototyping and small projects only.

A note on performance

All required BaseReferences are constructed when the graph is built. However, the content property is only evaluated on request. Therefore, loading data or performing expensive checks in the constructor will lead to poor performance. Instead, check the validity of arguments at construction, but load data only in the content property.

Adding as a local extension

To add WebReference as a local extension, create a new file.dotstop_extensions/references.py in the current working directory. All concrete implementations of the BaseReference class available in this namespace will now be usable within trudag, accessible using their type() method.

Packaging as a plugin

To mark a package as containing plugins, add the following entry point to its pyproject.toml:

[project.entry-points."trustable.reference.plugins"]
<ref> = <object>

All concrete BaseReference subclasses present in the entry point namespace will now be accessible, again by using their type() method.

Inbuilt reference types

trudag also exposes further reference classes, that can be used as is in references, or extended to create your own. These are:

Further documentation on their use can be found in the classes' docstrings.