orgroamtools package

Submodules

orgroamtools.data module

class orgroamtools.data.OrgLink(type: str, content: str, desc: str | None)[source]

Bases: object

Store information about org links

type

the type of link (e.g. https, file)

Type:: str

content

content of the link

Type:: str

desc

description of the link

Type:: Optional[str]

content: str

desc: str | None

type: str

class orgroamtools.data.RoamGraph(db: str)[source]

Bases: object

Store information of org-roam graph.

By default, the nodes in the _node_index are ordered ascending on the node IDs. In the documentation, the words “collection”, “network”, “graph”, all mean the same thing: the graph with nodes the org-roam nodes and edges determined by backlinks in the org-roam collection.

The location of the org-roam database is the value of (org-roam-db-location):

from orgroamtools.data import RoamGraph
collection = RoamGraph(LOCATION_OF_DB)

db_path

Path to org-roam database connected to graph

Type:: str

_id_title_map

Map with keys the id of nodes and values the titles of the corresponding nodes

Type:: dict[str,str]

_graph

networkx graph representation of the collection

Type:: nx.MultiDiGraph

_node_index

Map with keys the ID of nodes and values the RoamNode object that corresponds

Type:: dict[str, RoamNode]

_orphans

List of orphans in network. An orphan node is one with no links connecting it to any other node

Type:: list[RoamNode]

_is_connected

Tracks if network is connected (i.e. has no orphans)

Type:: bool

_duplicate_titles

List of duplicated titles in network, used for warning user

Type:: list[str]

_contains_dup_titles

Whether the collection has duplicated titles

Type:: bool

property IDs: list[str]

Return list of IDs present in network

Returns:: list of IDs in network
Return type:: list[str]

property adjacency_list: list[list[str]]

Return adjacency list of collection

An adjacency list is a (sometimes) more memory-efficient way to store the information of a graph. It stores edges of the graph instead of correspondences of nodes in a matrix for example. If a node a has an edge pointing to node b, the pair [a,b] will appear in the adjacency list. Keeping with the theme of this library, the node identifiers will be used to identify the nodes. All nodes will appear in the list, since by convention, an org-roam node always links to itself.

Returns:: Adjacency list of collection with node IDs to identify nodes
Return type:: list[list[str]]

all_tags() → set[str][source]

Return collection of all tags present in network

Returns:: Set of tags present in network
Return type:: set[str]

property backlink_index: dict[str, list[str]]

Return index for node backlinks of the collection

When a node in the collection has a reference to another node in the collection, it is said to have a backlink to that node. These backlinks provide the main nonhierarchical structure of the collection, and compactly express relations of different nodes to each other.

Returns:: dict with keys the IDs of nodes and values the list of backlinks in the node
Return type:: dict[str, list[str]]

property body_index: dict[str, str]

Return index of body text for each node.

Returns:: Index with value the body text of nodes
Return type:: dict[str, str]

property file_index: dict[str, str]

Return index of filenames of collection

Returns:: dict with keys the IDs of nodes and values the filename of the file containing that node
Return type:: dict[str, str]

filter_tags(tags: Iterable[str], exclude: bool = True) → RoamGraph[source]

Filter network by collection of tags

Parameters:

tags (Iterable[str]) – Tags to filter by
exclude (bool) – To exclude or not

Returns:

Filtered collection (as a copy)

Return type:

RoamGraph

Examples

>>> tags = {"tag1", "tag2"}
>>> filtered = collection.filter_tags(tags, exclude = True)
>>> filtered.refresh()
>>> print(tags.issubset(filtered.all_tags()))
False

property fnames: list[str]

Return list of filenames in network

Parameters:: base (bool) – get just basename of file
Returns:: list of filenames in network
Return type:: list[str]

get_body(identifier: str) → str[source]

Return body of node

Parameters:: identifier (str) – Node identifier. Can be ID or title
Returns:: Body text of node
Return type:: str
Raises:: AttributeError – If no node matches identifier

get_latex_snippets(identifier: str) → list[str][source]

Return latex snippets of node

Parameters:: identifier (str) – Node identifier. Can be ID or title.
Returns:: List of LaTeX snippets in node
Return type:: list[str]
Raises:: AttributeError – If no node matches the identifer

get_src_blocks(identifier: str) → list[Tuple[str, str]][source]

Return source blocks of node

Parameters:: identifier (str) – Node identifier. Can be ID or title.
Returns:: List of source blocks in format (LANGUAGE, BLOCK_BODY)
Return type:: list[Tuple[str,str]]
Raises:: AttributeError – If no node matches identifier

property graph: networkx.MultiDiGraph

Return networkx graph representation of collection

An org-roam collection naturally forms the structure of a multi directed graph: a graph with direction-sensitive edges allowing multiple edges between any two nodes.

Returns:: Multi directed graph representation of the collection
Return type:: nx.MultiDiGraph

property id_title_map: dict[str, str]

Return dictionary of how the network maps IDs to titles

Returns:: dict with keys node IDs and values the corresponding title of the node
Return type:: dic[str, str]

Examples

>>> ids = list(collection.id_title_map.keys())
>>> ids == collection.IDs
True

classmethod init_empty()[source]

Initialize empty RoamNode object

Return type:: RoamNode object with default fields initialized

property math_snippet_index: dict[str, list[str]]

Return latex snippet index

Returns:: Index of LaTeX snippets
Return type:: dict[str, list[str]]

property misc_link_index: dict[str, list[str]]

Return index of miscellaneous links

Returns:: dict with keys IDs of nodes and values the list of backlinks in that node
Return type:: dict[str, list[str]]

property misc_links: dict[str, list[OrgLink]]

Return list of lists of miscellaneous links

Returns:: dict with keys node IDs and values the list of miscellaneous IDs for corresponding node
Return type:: dict[str, list[str]]

node(identifier: str) → RoamNode[source]

Return node object

Internally a node is of class orgroamtools.data.RoamNode, which stores basic information about a node like ID, title, filename, and its backlinks

Parameters:: identifier (str) – Identifier for node. Can be title or ID
Returns:: RoamNode object of node
Return type:: RoamNode
Raises:: AttributeError – Raised if node cannot be found

node_id(identifier: str) → str[source]

Return ID of node

org-roam uses org-mode’s internal :ID: property creation to uniquely identify nodes in the collection.

Parameters:: identifier (str) – Title of node
Returns:: ID of node
Return type:: str
Raises:: AttributeError – Raised if no node matches the provided title

property node_index: dict[str, RoamNode]

Return index of nodes

The node_index is hashed by node ID, since this is the only value guaranteed to be unique to each org-roam node across various configurations.

Returns:: dict with keys the IDs of nodes and values the RoamNode object of the node with that ID
Return type:: dict[str, RoamNode]

node_links(identifier: str) → list[str][source]

Return links for a particular node

A node’s links is the collection of links made in the body of the node desired. By convention, a node will always refer to itself

Parameters:: identifier (str) – Identifier for node. Can be title or ID
Returns:: List of IDs of nodes the provided node refers to
Return type:: list[str]
Raises:: AttributeError – Raised if identifier cannot be found in the collection

node_title(identifier: str) → str[source]

Return title of node

The title of a node is the name given to the note file. If your org-roam node is its own file, this is the #+title: property. If you org-roam node is a heading, this is the heading title

Parameters:: identifier (str) – ID of node
Returns:: Title of node
Return type:: str
Raises:: AttributeError – Raised if ID not be found in collection

property nodes: list[RoamNode]

Return list of nodes in network

Returns:: list of nodes in network
Return type:: list[RoamNode]

refresh() → None[source]: Refresh _node_index-dependent data in collection after manual change to self._node_index.

remove_orphans() → RoamGraph[source]

Remove orphans from network

This method returns a new network that has orphans removed.

Returns:: Connected subcollection of self
Return type:: RoamGraph

Examples

>>> orphanless = collection.remove_orphans()
>>> orphanless.refresh()
>>> print(orphanless._is_connected)
True

property size: Tuple[int, int]

Return size of collection

Returns:: Tuple (num nodes , num links)
Return type:: Tuple[int, int]

property src_block_index: dict[str, list[tuple[str, str]]]

Return index of source blocks of nodes

Returns:: Index of source blocks. Source blocks are identified by Tuple[LANGUAGE, BLOCK_BODY]
Return type:: dict[str, list[Tuple[str,str]]]

property tag_index: dict[str, set[str]]

Return dictionary of IDs and the nodes’ tag sets

Returns:: dict with keys node IDs and values the set of tags of the node
Return type:: dic[str, set[str]]

property title_index: dict[str, str]

Return dictionary of how the network maps IDs to titles

Synonym for id_title_map.

Returns:: dict with keys node IDs and values the corresponding title of the node
Return type:: dic[str, str]

Examples

FIXME: Add docs.

property titles: list[str]

Return list of titles present in network

Returns:: list of titles of nodes in network
Return type:: list[str]

class orgroamtools.data.RoamNode(id: str, title: str, fname: str, tags: set[str], backlinks: list[str], misc_links: list[OrgLink])[source]

Bases: object

Store relevant org-roam node information

A node is an atomic note known to the org-roam database. It is uniquely determined by an ID generated at the time of creation, but has other identifiers and information that a user might want to know about.

id

Unique org ID of org-roam node

Type:: str

title

Title of org-roam node

Type:: str

fname

Filename of org-roam node

Type:: str

tags

Collection of tags of org-roam node

Type:: set[str]

backlinks

List of backlinks in org-roam node

Type:: list[str]

misc_links

List of miscellaneous links that are not links to other nodes

Type:: list[OrgLink]

backlinks: list[str]

property body: str

Return body of node

Returns:: Body text of node
Return type:: str

fname: str

id: str

misc_links: list[OrgLink]

tags: set[str]

title: str

orgroamtools package

Submodules

orgroamtools.data module

Module contents