Onya 0.1.1__py3-none-any.whl

onya/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

onya/__init__.py

@@ -0,0 +1,29 @@
+# onya
+
+'''
+Onya - Property graph model for Web resources
+'''
+
+from .__about__ import __version__ as __version__  # noqa: F401
+from amara.iri import I
+
+# Base IRI for Onya vocabulary
+ONYA_BASEIRI = I('http://purl.org/onya/vocab/')
+
+# Special null value for Onya
+ONYA_NULL = I('http://purl.org/onya/vocab/null')
+
+
+class LITERAL:
+    '''
+    Wrapper for literal (text) values in Onya
+    '''
+    def __init__(self, s):
+        self._s = s
+
+    def __str__(self):
+        return self._s
+
+    def __repr__(self):
+        return f'LITERAL({repr(self._s)})'
+

onya/contrib/mkdcomments.py

@@ -0,0 +1,54 @@
+"""
+A Python-Markdown preprocessor extension to ignore html comments opened by
+three dashes (<!---comment-->) and any whitespace prior to them. I believe
+pandoc has similar functionality.
+
+Note: This extension does not work with the markdownfromFile function or
+the convertFile method. They raise a UnicodeDecodeError.
+
+Note: If using multiple extensions, mkdcomments probably should be last in
+the list. Markdown extensions are loaded into the OrderedDict from which they
+are executed in the order of the extension list. If a different extension is
+loaded after mkdcomments, it may insert itself before mkdcomments in the
+OrderedDict. Undesirable results may ensue. If, for instance, the 'meta'
+extension is executed before mkdcomments, any comments in the meta-data will be
+included in meta's dictionary.
+"""
+
+import re
+from markdown.preprocessors import Preprocessor
+from markdown.extensions import Extension
+
+
+class CommentsExtension(Extension):
+    def extendMarkdown(self, md, md_globals):
+        md.registerExtension(self)
+        md.preprocessors.add("comments", CommentsProcessor(md), "_begin")
+
+
+class CommentsProcessor(Preprocessor):
+    def run(self, lines):
+        new_lines = []
+        multi = False
+        for line in lines:
+            if not multi:
+                multi = self._uncommenter(line)[1]
+                new_lines.append(self._uncommenter(line)[0])
+            else:
+                multi = self._unmultiliner(line)[1]
+                new_lines.append(self._unmultiliner(line)[0])
+        return new_lines
+
+    def _uncommenter(self, line):
+        if re.match(r'.*<!---.*-->', line):     # inline(could start multiline)
+            return self._uncommenter(re.sub(r'\s*<!---.*?-->', '', line))
+        elif re.match(r'.*<!---', line):        # start multiline
+            return [re.sub(r'\s*<!---.*', '', line), True]
+        else:                                   # no comment
+            return [line, False]
+
+    def _unmultiliner(self, line):
+        if re.match(r'.*-->', line):    # end multiline (could start comment)
+            return self._uncommenter(re.sub(r'.*?-->', '', line, count=1))
+        else:
+            return ['', True]                   # continue multiline

onya/graph.py

@@ -0,0 +1,182 @@
+'''
+Graph and other fundamental classes for Onya
+
+The Onya graph model:
+- A graph is a collection of nodes
+- Each node has:
+  - An identifier (IRI)
+  - A set of types (IRIs)
+  - A set of assertions (edges and properties)
+- Edges connect nodes to nodes via IRI labels
+- Properties connect nodes to string values via IRI labels
+- Both edges and properties are collectively called "assertions"
+- Each assertion is in effect an anonymous node defined by (origin IRI, assertion IRI)
+- Assertions can themselves be origins for further assertions (natural recursiveness)
+'''
+
+from __future__ import annotations
+from collections.abc import MutableMapping, Iterator
+from abc import ABC
+
+from amara.iri import I
+
+
+class assertions_mixin:
+    '''
+    Mixin for objects that can have assertions (edges and properties)
+    '''
+    def add_property(self, label: I | str, value: str):
+        p = property_(self, label, value)
+        self.properties.add(p)
+        return p
+
+    def add_edge(self, label: I | str, target: 'node'):
+        e = edge(self, label, target)
+        self.edges.add(e)
+        return e
+
+    def remove_property(self, prop: 'property_'):
+        self.properties.remove(prop)
+
+    def remove_edge(self, edge_: 'edge'):
+        self.edges.remove(edge_)
+
+    def getprop(self, label: I | str):
+        '''Get properties with a given label'''
+        for prop in self.properties:
+            if prop.label == label:
+                yield prop
+    
+    def getedge(self, label: I | str):
+        '''Get edges with a given label'''
+        for edge_ in self.edges:
+            if edge_.label == label:
+                yield edge_
+
+
+class node(assertions_mixin):
+    '''
+    A node in the Onya graph.
+    
+    A node has an identifier (IRI), optional types (IRIs), and assertions
+    (edges and properties). Both edges and properties are sets, not sequences,
+    because pervasive ordering is not a core requirement of the model.
+    '''
+    __slots__ = ['id', 'types', 'properties', 'edges']
+
+    def __init__(self, id_: I | str, types: I | str | set[I | str] | None = None):
+        self.id = id_
+        if isinstance(types, str):
+            types = I(types)
+        if isinstance(types, I):
+            types = {types}
+        self.types: set[I | str] = set(types) if types else set()
+        self.properties: set['property_'] = set()
+        self.edges: set['edge'] = set()
+    
+    def traverse(self, label: I | str) -> Iterator['edge']:
+        '''Find edges with a given label'''
+        for e in self.edges:
+            if e.label == label:
+                yield e
+
+    def reverse(self, label: I | str, graph: 'graph') -> Iterator['edge']:
+        '''Find edges targeting this node with a given label (requires graph access)'''
+        for nid, nobj in graph.nodes.items():
+            for e in nobj.traverse(label):
+                if e.target == self:
+                    yield e
+
+
+class assertion(assertions_mixin, ABC):
+    '''
+    Abstract base class for assertions (edges and properties)
+    
+    Each assertion is an anonymous node defined by the combination of
+    its origin and its label IRI.
+    '''
+    __slots__ = ['origin', 'label', 'properties', 'edges']
+    
+    def __init__(self, origin: 'node | assertion', label: I | str):
+        self.origin = origin
+        self.label = label
+        self.properties: set['property_'] = set()
+        self.edges: set['edge'] = set()
+
+
+class property_(assertion):
+    '''
+    A property assertion connects an origin to a string value via an IRI label.
+    
+    Properties in Onya are simple: they always have string values.
+    No numbers, dates, or other types at the core layer - those can be
+    handled by annotation systems built on top.
+    '''
+    __slots__ = ['value']
+
+    def __init__(self, origin: 'node | assertion', label: I | str, value: str):
+        super().__init__(origin, label)
+        self.value: str = value
+    
+    def __repr__(self):
+        return f'property_({self.label}={self.value!r})'
+
+
+class edge(assertion):
+    '''
+    An edge assertion connects an origin node to a target node via an IRI label.
+    '''
+    __slots__ = ['target']
+
+    def __init__(self, origin: 'node | assertion', label: I | str, target: 'node'):
+        super().__init__(origin, label)
+        self.target: 'node' = target
+    
+    def __repr__(self):
+        return f'edge({self.label} -> {self.target.id})'
+
+
+class graph(MutableMapping):
+    '''
+    A collection of nodes managed and queried together.
+    
+    This is the top-level container for an Onya graph.
+    '''
+    def __init__(self, nodes: list[node] = ()):
+        self.nodes: dict[I | str, node] = {}
+        self.nodes.update({n.id: n for n in nodes})
+
+    def __getitem__(self, key: I | str) -> node:
+        return self.nodes[key]
+
+    def __delitem__(self, nid: I | str) -> None:
+        del self.nodes[nid]
+
+    def __setitem__(self, nid: I | str, nobj: node) -> None:
+        self.nodes[nid] = nobj
+
+    def __iter__(self) -> Iterator[I | str]:
+        return iter(self.nodes)
+
+    def __len__(self) -> int:
+        return len(self.nodes)
+
+    def __repr__(self) -> str:
+        return f'{type(self).__name__} with {len(self.nodes)} nodes'
+
+    def node(self, nid: I | str, types: I | str | set[I | str] | None = None) -> node:
+        '''
+        Convenience for constructing, then adding a new node to the graph
+        '''
+        n = node(nid, types)
+        self[nid] = n
+        return n
+
+    def typematch(self, types: I | str | set[I | str]) -> Iterator[node]:
+        '''Find nodes with matching types'''
+        if isinstance(types, (str, I)):
+            types = {types}
+        types_set = set(types)
+        for n in self.nodes.values():
+            if n.types & types_set:
+                yield n

onya/serial/__init__.py

@@ -0,0 +1,5 @@
+# onya.serial
+
+'''
+Onya serializers and deserializers
+'''

onya/serial/literate.py

@@ -0,0 +1,116 @@
+# onya.serial.literate
+
+"""
+Serialize and deserialize between an Onya model and Onya Literate (Markdown)
+
+see: doc/literate_format.md
+
+"""
+
+import sys
+
+from amara import iri
+
+from onya import I, ONYA_BASEIRI
+
+# from onya.serial.litparse_util import parse
+
+TYPE_REL = I(iri.absolutize('type', ONYA_BASEIRI))
+
+__all__ = ['read', 'write',
+    # Non-standard
+    'longtext',
+]
+
+
+def longtext(t):
+    '''
+    Prepare long text to be e.g. included as an Onya literate property value,
+    according to markdown rules
+
+    Only use this function if you're Ok with possible whitespace-specific changes
+
+    >>> from onya.serial.literate import longtext
+    >>> longtext()
+    '''
+# >>> markdown.markdown('* abc\ndef\nghi')
+# '<ul>\n<li>abc\ndef\nghi</li>\n</ul>'
+# >>> markdown.markdown('* abc\n\ndef\n\nghi')
+# '<ul>\n<li>abc</li>\n</ul>\n<p>def</p>\n<p>ghi</p>'
+# >>> markdown.markdown('* abc\n\n    def\n\n    ghi')
+# '<ul>\n<li>\n<p>abc</p>\n<p>def</p>\n<p>ghi</p>\n</li>\n</ul>'
+
+    # Insert blank line after list item & before start of secondary paragraph.
+    # Indent the line with at least one space to ensure it is indented as part of the list.
+    endswith_cr = t[-1] == '\n'
+    new_t = t.replace('\n', '\n    ')
+    if endswith_cr:
+        new_t = new_t[:-5]
+    return new_t
+
+
+def abbreviate(rel, bases):
+    for base in bases:
+        abbr = iri.relativize(rel, base, subPathOnly=True)
+        if abbr:
+            if base is ONYA_BASEIRI:
+                abbr = '@' + abbr
+            return abbr
+    return I(rel)
+
+
+def value_format(val):
+    if isinstance(val, I):
+        return f'<{val}>'
+    else:
+        return f'"{val}"'
+
+
+def write(model, out=sys.stdout, base=None, propertybase=None, shorteners=None):
+    '''
+    models - input Onya model from which output is generated
+    '''
+    shorteners = shorteners or {}
+
+    all_propertybase = [propertybase] if propertybase else []
+    all_propertybase.append(ONYA_BASEIRI)
+
+    if any((base, propertybase, shorteners)):
+        out.write('# @docheader\n\n* @iri:\n')
+    if base:
+        out.write('    * @base: {0}'.format(base))
+    #for k, v in shorteners:
+    #    out.write('    * @base: {0}'.format(base))
+
+    out.write('\n\n')
+
+    # Get all origin nodes from the model (all node IDs in the graph)
+    origin_space = set(model.keys()) if hasattr(model, 'keys') else set()
+
+    for o in origin_space:
+        out.write('# {0}\n\n'.format(o))
+        for o_, r, t, a in model.match(o):
+            rendered_r = abbreviate(r, all_propertybase)
+            if isinstance(rendered_r, I):
+                rendered_r = f'<{rendered_r}>'
+            value_format(t)
+            out.write(f'* {rendered_r}: {value_format(t)}\n')
+            for k, v in a.items():
+                rendered_k = abbreviate(k, all_propertybase)
+                if isinstance(rendered_k, I):
+                    rendered_r = f'<{rendered_k}>'
+                out.write(f'    * {rendered_k}: {value_format(t)}\n')
+
+        out.write('\n')
+    return
+
+
+def read(fp, g):
+    '''
+    Read Onya Literate format from file pointer into graph
+
+    fp -- file pointer to read from
+    g -- graph to populate
+    '''
+    # TODO: Implement this using literate_lex.parse
+    pass

onya/serial/literate_lex.py

@@ -0,0 +1,523 @@
+# -*- coding: utf-8 -*-
+# onya.serial.literate_lex.py
+'''
+Main body of the Onya Literate parser
+
+Onya Literate, or Onya Lit, is a Markdown-based format
+
+Proper entry point of use is onya.serial.literate
+
+see: doc/literate_format.md
+
+'''
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+from amara import iri  # for absolutize & matches_uri_syntax
+
+from onya import I, ONYA_BASEIRI, ONYA_NULL, LITERAL
+
+from pyparsing import (
+    ParserElement, Literal, htmlComment, Optional, Word, alphas, alphanums,
+    Combine, MatchFirst, QuotedString, Regex, ZeroOrMore, White, Suppress,
+    Group, delimited_list, Forward, OneOrMore, rest_of_line
+)  # pip install pyparsing
+ParserElement.setDefaultWhitespaceChars(' \t')
+
+URI_ABBR_PAT = re.compile('@([\\-_\\w]+)([#/@])(.+)', re.DOTALL)
+URI_EXPLICIT_PAT = re.compile('<(.+)>', re.DOTALL)
+
+TYPE_REL = ONYA_BASEIRI('type')
+
+class value_type(Enum):
+    '''
+    Basic typing info for values (really just text vs node reference)
+    '''
+    TEXT_VAL = 1
+    RES_VAL = 2
+    UNKNOWN_VAL = 3
+
+
+# For parse trees
+@dataclass
+class prop_info:
+    indent: int = None      # 
+    key: str = None         # 
+    value: list = None      # 
+    children: list = None   # 
+    is_text_ref: bool = False  # True if this is a text reference (uses ::)
+    multiline_text: str = None  # For storing multiline text content
+
+
+@dataclass
+class doc_info:
+    iri: str = None         # iri of the doc being parsed, itself
+    nodebase: str = None    # used to resolve relative node IRIs
+    schemabase: str = None  # used to resolve relative schema IRIs
+    typebase: str = None    # used to resolve relative type IRIs 
+    lang: str = None        # other IRI abbreviations
+    iris: dict = None       # iterpretations of untyped values (e.g. string vs list of strs vs IRI)
+    text_refs: dict = None  # text references defined with :name = """content"""
+
+
+@dataclass
+class value_info:
+    verbatim: int = None    # Literal value input text
+    typeindic: int = None   # Value type indicator (from value_type enum)
+
+
+def _make_tree(string, location, tokens):
+    '''
+    Parse action to return a parsed tree node from tokens
+    '''
+    return prop_info(indent=len(tokens[0]), key=tokens[1],
+                        value=tokens[2], children=None)
+
+
+def _make_value(string, location, tokens):
+    '''
+    Parse action to make sure the right type of value is created during parse
+    '''
+    val = tokens[0]
+    # Must check IRI first, since it is a subclass of str
+    if isinstance(val, I):
+        typeindic = value_type.RES_VAL
+    elif isinstance(val, LITERAL):
+        typeindic = value_type.TEXT_VAL
+    elif isinstance(val, str):
+        val = val.strip()
+        typeindic = value_type.UNKNOWN_VAL
+
+    return value_info(verbatim=val, typeindic=typeindic)
+
+
+def literal_parse_action(toks):
+    '''
+    Parse action to coerce to literal value
+    '''
+    return LITERAL(toks[0])
+
+
+def iriref_parse_action(toks):
+    '''
+    Parse action to coerce to IRI reference value
+    '''
+    return I(toks[0])
+
+RIGHT_ARROW     = Literal('->') | Literal('→')  # U+2192
+DOUBLE_COLON    = Literal('::')  # For text references
+
+COMMENT         = htmlComment  # Using HTML-style comments for cleaner markdown compatibility
+OPCOMMENT       = Optional(COMMENT)
+IDENT           = Word(alphas, alphanums + '_' + '-')
+IDENT_KEY       = Combine(Optional('@') + IDENT).leaveWhitespace()
+# EXPLICIT_IRI    = QuotedString('<', end_quote_char='>')
+QUOTED_STRING   = MatchFirst((QuotedString('"', escChar='\\'), QuotedString("'", escChar='\\'))) \
+                    .setParseAction(literal_parse_action)
+# Triple-quoted strings for text references - handle multiline properly
+TRIPLE_QUOTED_STRING = Regex(r'"""([^"]*(?:"[^"]*)*?)"""', re.DOTALL) \
+                        .setParseAction(lambda tokens: LITERAL(tokens[0]))
+# See: https://rdflib.readthedocs.io/en/stable/_modules/rdflib/plugins/sparql/parser.html
+IRIREF          = Regex(r'[^<>"{}|^`\\\[\]%s]*' % "".join(
+                        "\\x%02X" % i for i in range(33)
+                    )) \
+                    .setParseAction(iriref_parse_action)
+#REST_OF_LINE = rest_of_line.leave_whitespace()
+
+blank_to_eol    = ZeroOrMore(COMMENT) + White('\n')
+explicit_iriref = Combine(Suppress("<") + IRIREF + Suppress(">")) \
+                    .setParseAction(iriref_parse_action)
+
+# Text reference definition: :name = """content"""
+text_ref_def    = Suppress(':') + IDENT + Suppress('=') + TRIPLE_QUOTED_STRING
+
+value_expr      = ( explicit_iriref + Suppress(ZeroOrMore(COMMENT)) ) | ( QUOTED_STRING + Suppress(ZeroOrMore(COMMENT)) ) | rest_of_line  # noqa: E501
+prop            = Optional(White(' \t').leaveWhitespace(), '') + Suppress('*' + White()) + \
+                    ( explicit_iriref | IDENT_KEY | IRIREF ) + Suppress(':') + Optional(value_expr, None)
+# Text reference property: label:: reference_name
+prop_text_ref   = Optional(White(' \t').leaveWhitespace(), '') + Suppress('*' + White()) + \
+                    ( explicit_iriref | IDENT_KEY | IRIREF ) + Suppress(DOUBLE_COLON) + Optional(IRIREF, None)
+edge            = Optional(White(' \t').leaveWhitespace(), '') + Suppress('*' + White()) + \
+                    ( explicit_iriref | IDENT_KEY | IRIREF ) + Suppress(RIGHT_ARROW) + Optional(value_expr, None)
+propset         = Group(delimited_list(prop_text_ref | prop | edge | COMMENT, delim='\n'))
+node_header = Word('#') + Optional(IRIREF, None) + Optional(QuotedString('[', end_quote_char=']'), None)
+node_block  = Forward()
+node_block  << Group(node_header + White('\n').suppress() + Suppress(ZeroOrMore(blank_to_eol)) + propset)
+
+# Start symbol - allow text reference definitions anywhere
+node_seq    = OneOrMore(
+                    Suppress(ZeroOrMore(blank_to_eol)) + \
+                        (node_block | text_ref_def) + Optional(White('\n')).suppress() + \
+                            Suppress(ZeroOrMore(blank_to_eol))
+                    )
+
+def _make_text_ref_tree(string, location, tokens):
+    '''
+    Parse action to return a parsed tree node for text references
+    '''
+    return prop_info(indent=len(tokens[0]), key=tokens[1],
+                        value=tokens[2] if len(tokens) > 2 else None, children=None,
+                        is_text_ref=True)
+
+def parse_multiline_text(lines, start_idx, current_indent):
+    """
+    Parse multiline text that continues after a property definition.
+    Returns (text_content, next_line_idx)
+    """
+    if start_idx >= len(lines):
+        return "", start_idx
+
+    text_lines = []
+    i = start_idx
+
+    while i < len(lines):
+        line = lines[i]
+
+        # Skip empty lines
+        if not line.strip():
+            i += 1
+            continue
+
+        # Check if this line is indented enough to be part of the multiline text
+        # Must be indented more than the current property level
+        line_indent = len(line) - len(line.lstrip())
+        if line_indent > current_indent:
+            # This is a continuation line
+            text_lines.append(line[current_indent:])  # Remove the base indentation
+            i += 1
+        else:
+            # This line is not indented enough, stop parsing multiline text
+            break
+
+    return '\n'.join(text_lines), i
+
+def _make_text_ref_def(string, location, tokens):
+    '''
+    Parse action for text reference definitions
+    '''
+    return ('text_ref_def', tokens[0], tokens[1])
+
+prop.setParseAction(_make_tree)
+prop_text_ref.setParseAction(_make_text_ref_tree)
+edge.setParseAction(_make_tree)
+text_ref_def.setParseAction(_make_text_ref_def)
+value_expr.setParseAction(_make_value)
+
+
+def parse(lit_text, graph_obj, encoding='utf-8'):
+    """
+    Translate Onya Literate text into Onya graph
+
+    lit_text -- Onya Literate source text
+    graph_obj -- Onya graph to populate
+    encoding -- character encoding (defaults to UTF-8)
+
+    Returns: The document IRI from @document header, or None
+
+    >>> from onya.driver.memory import newmodel
+    >>> from onya.serial.literate import parse # Delegates to literate_lex.parse
+    >>> m = newmodel()
+    >>> parse(open('test/resource/poetry.onya').read(), m)
+    'http://uche.ogbuji.net/poems/'
+    >>> m.size()
+    40
+    >>> next(m.match(None, 'http://uche.ogbuji.net/poems/updated', '2013-10-15'))
+    (I(http://uche.ogbuji.net/poems/1), I(http://uche.ogbuji.net/poems/updated), '2013-10-15', {})
+    """
+    # Set up document parameters
+    doc = doc_info()
+    doc.iris = {}  # Initialize the iris dictionary
+    doc.text_refs = {}  # Initialize the text references dictionary
+
+    parsed = node_seq.parseString(lit_text, parseAll=True)
+
+    # First pass: collect all text reference definitions
+    for item in parsed:
+        if isinstance(item, tuple) and item[0] == 'text_ref_def':
+            ref_name, ref_content = item[1], item[2]
+            doc.text_refs[ref_name] = str(ref_content)
+
+    # Second pass: process node blocks
+    for item in parsed:
+        if not (isinstance(item, tuple) and item[0] == 'text_ref_def'):
+            # Handle node blocks
+            process_nodeblock(item, graph_obj, doc)
+
+    return doc.iri
+
+
+def expand_iri(iri_in, base, nodecontext=None, doc=None):
+    if iri_in is None:
+        return ONYA_NULL
+    # Abreviation for special, Onya-specific properties
+    if iri_in.startswith('@'):
+        return I(iri.absolutize(iri_in[1:], ONYA_BASEIRI))
+
+    # Is it an explicit IRI (i.e. with <…>)?
+    if iri_match := URI_EXPLICIT_PAT.match(iri_in):
+        return iri_match.group(1) if base is None else I(iri.absolutize(iri_match.group(1), base))
+
+    # XXX Clarify this bit?
+    if iri_match := URI_ABBR_PAT.match(iri_in):
+        if doc is None or doc.iris is None:
+            raise ValueError(f'IRI abbreviation "{iri_match.group(1)}" used but no doc context provided')
+        uri = doc.iris[iri_match.group(1)]
+        fulliri = URI_ABBR_PAT.sub(uri + '\\2\\3', iri_in)
+    else:
+        # Replace upstream ValueError with our own
+        if nodecontext and not(iri.matches_uri_ref_syntax(iri_in)):
+            # FIXME: Replace with a Onya-specific error
+            raise ValueError(f'Invalid IRI reference provided for node context {nodecontext}: "{iri_in}"')
+        fulliri = iri_in if base is None else I(iri.absolutize(iri_in, base))
+    return I(fulliri)
+
+
+def process_nodeblock(nodeblock, graph_obj, doc):
+    headermarks, nid, ntype, props = nodeblock
+
+    if nid == '@docheader':
+        process_docheader(props, graph_obj, doc)
+        return
+
+    nid = expand_iri(nid, doc.nodebase, doc=doc)
+
+    # Get or create the node
+    if nid not in graph_obj:
+        n = graph_obj.node(nid)
+    else:
+        n = graph_obj[nid]
+
+    # Add type if specified
+    if ntype:
+        type_iri = expand_iri(ntype, doc.typebase, doc=doc)
+        n.types.add(type_iri)
+
+    # Track current assertion for nested assertions
+    outer_indent = -1
+    current_assertion = None
+
+    for prop_info in props:
+        if isinstance(prop_info, str):
+            # Just a comment. Skip.
+            continue
+
+        # Handle text reference definitions
+        if isinstance(prop_info, tuple) and prop_info[0] == 'text_ref_def':
+            ref_name, ref_content = prop_info[1], prop_info[2]
+            doc.text_refs[ref_name] = str(ref_content)
+            continue
+
+        # First assertion encountered determines outer indent
+        if outer_indent == -1:
+            outer_indent = prop_info.indent
+
+        # Expand the assertion label IRI
+        assertion_label = expand_iri(prop_info.key, doc.schemabase, doc=doc)
+
+        if prop_info.indent == outer_indent:
+            # This is a top-level assertion
+            if prop_info.is_text_ref:
+                # Handle text reference
+                ref_name = str(prop_info.value) if prop_info.value else None
+                if ref_name and ref_name in doc.text_refs:
+                    str_val = doc.text_refs[ref_name]
+                    current_assertion = n.add_property(assertion_label, str_val)
+                else:
+                    # Text reference not found, skip or use empty string
+                    current_assertion = n.add_property(assertion_label, "")
+            elif prop_info.value:
+                val, typeindic = prop_info.value.verbatim, prop_info.value.typeindic
+
+                if typeindic == value_type.RES_VAL:
+                    # This is an edge (node to node)
+                    target_id = expand_iri(val, doc.typebase, doc=doc)
+                    # Get or create Janelaet node
+                    if target_id not in graph_obj:
+                        target_node = graph_obj.node(target_id)
+                    else:
+                        target_node = graph_obj[target_id]
+                    # Add edge and track it for nested assertions
+                    current_assertion = n.add_edge(assertion_label, target_node)
+                elif typeindic == value_type.TEXT_VAL or typeindic == value_type.UNKNOWN_VAL:
+                    # This is a property (node to string value)
+                    str_val = str(val)
+                    current_assertion = n.add_property(assertion_label, str_val)
+
+        else:
+            # This is a nested assertion on current_assertion
+            if current_assertion is None:
+                continue  # Skip nested without a parent
+
+            if prop_info.is_text_ref:
+                # Handle nested text reference
+                ref_name = str(prop_info.value) if prop_info.value else None
+                if ref_name and ref_name in doc.text_refs:
+                    str_val = doc.text_refs[ref_name]
+                    current_assertion.add_property(assertion_label, str_val)
+            elif prop_info.value:
+                val, typeindic = prop_info.value.verbatim, prop_info.value.typeindic
+                if typeindic == value_type.RES_VAL:
+                    # Nested edge
+                    target_id = expand_iri(val, doc.typebase, doc=doc)
+                    if target_id not in graph_obj:
+                        target_node = graph_obj.node(target_id)
+                    else:
+                        target_node = graph_obj[target_id]
+                    current_assertion.add_edge(assertion_label, target_node)
+                elif typeindic == value_type.TEXT_VAL or typeindic == value_type.UNKNOWN_VAL:
+                    # Nested property
+                    str_val = str(val)
+                    current_assertion.add_property(assertion_label, str_val)
+
+
+def process_docheader(props, graph_obj, doc):
+    outer_indent = -1
+    current_outer_prop = None
+    for prop in props:
+        # Skip comments
+        if isinstance(prop, str):
+            continue
+
+        # @iri section is where key IRI prefixes can be set
+        # First property encountered determines outer indent
+        if outer_indent == -1:
+            outer_indent = prop.indent
+        if prop.indent == outer_indent:
+            current_outer_prop = prop
+            #Setting an IRI for this very document being parsed
+            if prop.key == '@document':
+                doc.iri = prop.value.verbatim if prop.value else None
+            elif prop.key == '@language':
+                doc.lang = prop.value.verbatim if prop.value else None
+            elif prop.key == '@base':
+                doc.nodebase = doc.typebase = prop.value.verbatim if prop.value else None
+            elif prop.key == '@schema':
+                doc.schemabase = prop.value.verbatim if prop.value else None
+            elif prop.key == '@resource-type' or prop.key == '@type-base':
+                doc.typebase = prop.value.verbatim if prop.value else None
+            #If we have a document node to which to attach them, just attach all other properties
+            elif doc.iri:
+                # Create document node if needed
+                if doc.iri not in graph_obj:
+                    doc_node = graph_obj.node(doc.iri)
+                else:
+                    doc_node = graph_obj[doc.iri]
+
+                fullprop = I(iri.absolutize(prop.key, doc.schemabase))
+                if prop.value:
+                    doc_node.add_property(fullprop, prop.value.verbatim)
+        else:
+            # Handle nested properties (attributes)
+            if current_outer_prop and current_outer_prop.key == '@iri':
+                k, uri = prop.key, prop.value.verbatim if prop.value else None
+                if k == '@base':
+                    doc.nodebase = doc.typebase = uri
+                elif k == '@schema':
+                    doc.schemabase = uri
+                elif k == '@resource-type' or k == '@type-base':
+                    doc.typebase = uri
+                else:
+                    doc.iris[k] = uri
+    return
+
+
+'''
+def handle_resourceset(ltext, **kwargs):
+    'Helper that converts sets of resources from a textual format such as Markdown, including absolutizing relative IRIs'
+    fullprop=kwargs.get('fullprop')
+    rid=kwargs.get('rid')
+    base=kwargs.get('base', ONYA_BASEIRI)
+    model=kwargs.get('model')
+    iris = ltext.strip().split()
+    for i in iris:
+        model.add(rid, fullprop, I(iri.absolutize(i, base)))
+    return None
+
+
+PREP_METHODS = {
+    ONYA_BASEIRI + 'text': lambda x, **kwargs: x,
+    # '@text': lambda x, **kwargs: x,
+    ONYA_BASEIRI + 'resource': lambda x, base=ONYA_BASEIRI, **kwargs: I(iri.absolutize(x, base)),
+    ONYA_BASEIRI + 'resourceset': handle_resourceset,
+}
+
+    from onya.driver.memory import newmodel
+    m = newmodel()
+    parse(open('/tmp/poetry.md').read(), m)
+    print(m.size())
+    import pprint; pprint.pprint(list(m.match()))
+    # next(m.match(None, 'http://uche.ogbuji.net/poems/updated', '2013-10-15'))
+'''  # noqa: E501
+
+'''
+
+for s in [  ' "quick-brown-fox"',
+            ' "quick-brown-fox"\n',
+            ' <quick-brown-fox>',
+            ' <quick-brown-fox>\n',
+            ' <quick-brown-fox> <!-- COMMENT -->',
+            ' "quick-brown-fox" <!-- COMMENT -->',
+            '"\"1\""',
+            ]:
+    parsed = value_expr.parseString(s, parseAll=True)
+    print(s, '∴', parsed)
+
+for s in [  '# resX\n<!-- COMMENT -->\n\n  * a-b-c: <quick-brown-fox>',
+            ]:
+    print(s, end='')
+    parsed = resource_block.parseString(s, parseAll=True)
+    print('∴', parsed)
+
+for s in [  '  * a-b-c: <quick-brown-fox>',
+            '  * a-b-c:  quick brown fox',
+            '  * a-b-c: " quick brown fox"',
+            ]:
+    parsed = prop.parseString(s, parseAll=True)
+    print(s, '∴', parsed)
+
+for s in [  '# resX\n  * a-b-c: <quick-brown-fox>',
+            '# resX [Person]\n  * a-b-c: <quick-brown-fox>',
+            '# resX [Person]\n  * a-b-c: <quick-brown-fox>\n  * d-e-f: "lazy dog"',
+            ]:
+    parsed = resource_block.parseString(s, parseAll=True)
+    print(s, '∴', parsed)
+
+for s in [  '# resX\n  * a-b-c: <quick-brown-fox>\n    lang: en',
+            ]:
+    parsed = resource_block.parseString(s, parseAll=True)
+    print(s, '∴', parsed)
+
+for s in [  '# res1\n<!-- COMMENT -->\n\n  * a-b-c: <quick-brown-fox>\n\n\n# res2\n\n  * d-e-f: <jumps-over>\n\n\n',
+            ]:
+    print(s, end='')
+    parsed = resource_block.parseString(s, parseAll=True)
+    print('∴', parsed)
+
+for s in [  '# res1\n<!-- COMMENT -->\n\n  * a-b-c: <quick-brown-fox>\n\n\n\n\n# res2\n\n  * d-e-f: <jumps-over>\n\n\n',
+            ]:
+    print(s, end='')
+    parsed = resource_seq.parseString(s, parseAll=True)
+    print('∴', parsed)
+
+'''  # noqa: E501, E502
+
+
+'''
+
+  a-b-c: <quick-brown-fox> ∴ [prop_info(key='a-b-c', value=ParseResults([I(quick-brown-fox)], {}), children=[ParseResults([], {})])]
+  a-b-c:  quick brown fox ∴ [prop_info(key='a-b-c', value=ParseResults(['quick brown fox'], {}), children=[ParseResults([], {})])]
+  a-b-c: " quick brown fox" ∴ [prop_info(key='a-b-c', value=ParseResults([LITERAL(' quick brown fox')], {}), children=[ParseResults([], {})])]
+# resX
+  a-b-c: <quick-brown-fox> ∴ [I(resX), None, prop_info(key='a-b-c', value=ParseResults([I(quick-brown-fox)], {}), children=[ParseResults([], {})])]
+# resX [Person]
+  a-b-c: <quick-brown-fox> ∴ [I(resX), 'Person', prop_info(key='a-b-c', value=ParseResults([I(quick-brown-fox)], {}), children=[ParseResults([], {})])]
+# resX [Person]
+  a-b-c: <quick-brown-fox>
+  d-e-f: "lazy dog" ∴ [I(resX), 'Person', prop_info(key='a-b-c', value=ParseResults([I(quick-brown-fox)], {}), children=[ParseResults([prop_info(key='d-e-f', value=LITERAL('lazy dog'), children=[])], {})])]
+# resX
+  a-b-c: <quick-brown-fox>
+    lang: en ∴ [I(resX), None, prop_info(key='a-b-c', value=ParseResults([I(quick-brown-fox)], {}), children=[ParseResults([prop_info(key='lang', value='en', children=[])], {})])]
+
+'''  # noqa: E501, E502

onya/serial/litparse_util.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+# onya.serial.litparse_util.py
+'''
+Utility wrapper for Onya Literate parser
+
+Provides a simple interface to the pyparsing-based parser in literate_lex
+'''
+
+from onya.serial import literate_lex
+
+
+class parser:
+    '''
+    Reusable object for parsing Onya Literate
+
+    This is a simple wrapper around the pyparsing-based parser
+    implementation in literate_lex.
+    '''
+    def __init__(self, config=None, encoding='utf-8'):
+        '''
+        Initialize the parser
+
+        config -- optional configuration dict
+        encoding -- character encoding (defaults to UTF-8)
+        '''
+        self.config = config or {}
+        self.encoding = encoding
+
+    def run(self, lit_text, g):
+        '''
+        Parse Onya Literate text into an Onya graph
+
+        lit_text -- Onya Literate source text
+        g -- Onya graph to populate with parsed relationships
+        encoding -- character encoding (defaults to UTF-8)
+
+        Returns: tuple of (docheader, nodes) where:
+            - docheader: document header info (may be None)
+            - nodes: set of nodes parsed from the document
+        '''
+        # Track nodes before parsing
+        nodes_before = set(g.nodes.keys())
+
+        # Parse the literate text using the pyparsing implementation
+        doc_iri = literate_lex.parse(lit_text, g, encoding=self.encoding)
+
+        # Get nodes that were added during parsing
+        nodes_after = set(g.nodes.keys())
+        nodes = nodes_after - nodes_before
+
+        # Return doc_iri as docheader (for compatibility)
+        docheader = doc_iri
+
+        return docheader, nodes

onya/terms.py

@@ -0,0 +1,18 @@
+'''
+Commonly used IRIs as vocabulary terms
+'''
+
+from amara.iri import I
+
+# Onya
+
+ONYA = I('http://purl.org/onya/vocab')
+ONYA_TYPE = ONYA('type')
+
+# RDF
+
+RDF_NS = I('http://www.w3.org/1999/02/22-rdf-syntax-ns#')
+RDFS_NS = I('http://www.w3.org/2000/01/rdf-schema#')
+
+RDF_TYPE = RDF_TYPE = RDF_NS('type')
+

onya/version.py

@@ -0,0 +1,2 @@
+# http://legacy.python.org/dev/peps/pep-0440/
+version_info = ('0', '0', '1')

onya-0.1.1.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: Onya
+Version: 0.1.1
+Summary: Knowledge graph (property graph-style) model and serialization for web resources
+Project-URL: Homepage, https://github.com/OoriData/Onya
+Project-URL: Repository, https://github.com/OoriData/Onya
+Project-URL: Issues, https://github.com/OoriData/Onya/issues
+Author-email: Uche Ogbuji <uche@ogbuji.net>
+License: Apache-2.0
+License-File: LICENSE-spec
+Keywords: data,graph,linked-data,rdf,web
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: amara>=4.0.1
+Requires-Dist: markdown
+Requires-Dist: pyparsing
+Provides-Extra: demo
+Requires-Dist: fire; extra == 'demo'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pipdeptree; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+**Onya** is a knowledge graph expression and implementation. This repository combines a [data model and format spec](SPEC.md) with a Python parser and API implementation.
+
+# Python quick start
+
+## Installation
+
+<!--
+```bash
+pip install amara
+```
+
+Or with uv (recommended):
+
+```bash
+uv pip install amara
+```
+-->
+
+Requires Python 3.12 or later. The package is still in early development, so install directly from source:
+
+```bash
+git clone https://github.com/OoriData/Onya.git
+cd Onya
+pip install -U .
+```
+
+<!--
+pip install git+https://github.com/OoriData/Onya.git
+-->
+
+## Basic Usage
+
+Here's a simple example demonstrating the core Onya API. First, let's define a small friendship graph in Onya Literate format:
+
+```
+# @docheader
+
+* @document: http://example.org/friendship-graph
+* @base: http://example.org/people/
+* @schema: https://schema.org/
+* @type-base: https://schema.org/
+
+# Chuks [Person]
+
+* name: Chukwuemeka Okafor
+* nickname: Chuks
+* age: 28
+
+# Ify [Person]
+
+* name: Ifeoma Adebayo
+* nickname: Ify
+* age: 27
+```
+
+Now let's parse this graph and interact with it using the Python API:
+
+```python
+from onya.graph import graph
+from onya.serial import literate_lex
+
+# Parse the Onya Literate text into a graph
+onya_text = '''
+# @docheader
+
+* @document: http://example.org/friendship-graph
+* @base: http://example.org/people/
+* @schema: https://schema.org/
+* @type-base: https://schema.org/
+
+# Chuks [Person]
+
+* name: Chukwuemeka Okafor
+* nickname: Chuks
+* age: 28
+
+# Ify [Person]
+
+* name: Ifeoma Adebayo
+* nickname: Ify
+* age: 27
+'''
+
+g = graph()
+doc_iri = literate_lex.parse(onya_text, g)
+print(f"Parsed document: {doc_iri}")
+print(f"Graph has {len(g)} nodes")
+
+# Access nodes and their properties
+chuks = g['http://example.org/people/Chuks']
+ify = g['http://example.org/people/Ify']
+
+# Get a specific property value
+for prop in chuks.getprop('https://schema.org/name'):
+    print(f"Name: {prop.value}")
+
+# Add a friendship edge between Chuks and Ify
+friendship = chuks.add_edge('https://schema.org/knows', ify)
+print(f"Added edge: {friendship}")
+
+# Add nested properties to the friendship (metadata about the relationship)
+friendship.add_property('https://schema.org/startDate', '2018-03-15')
+friendship.add_property('https://schema.org/description', 'Met at university')
+
+# Add a new property to Ify
+ify.add_property('https://schema.org/jobTitle', 'Software Engineer')
+
+# Modify a property by removing the old one and adding a new one
+age_props = list(chuks.getprop('https://schema.org/age'))
+for prop in age_props:
+    chuks.remove_property(prop)
+chuks.add_property('https://schema.org/age', '29')
+
+# Traverse edges
+for edge in chuks.traverse('https://schema.org/knows'):
+    friend = edge.target
+    for name_prop in friend.getprop('https://schema.org/name'):
+        print(f"Chuks knows: {name_prop.value}")
+    # Access nested properties on the edge
+    for date_prop in edge.getprop('https://schema.org/startDate'):
+        print(f"  Friends since: {date_prop.value}")
+
+# Find all nodes of a certain type
+for person in g.typematch('https://schema.org/Person'):
+    for name_prop in person.getprop('https://schema.org/name'):
+        print(f"Person in graph: {name_prop.value}")
+```
+
+This example demonstrates:
+- Parsing Onya Literate format
+- Accessing nodes and properties
+- Adding edges with nested properties (reified relationships)
+- Modifying properties
+- Traversing the graph
+- Querying by type
+
+# Background
+
+Onya is based on experience from developing [Versa](https://github.com/uogbuji/versa) and also working on [the MicroXML spec](https://dvcs.w3.org/hg/microxml/raw-file/tip/spec/microxml.html) and implementations thereof.
+
+The URL used for metavocabulary is [managed via purl.org](https://purl.archive.org/purl/onya/vocab).
+
+The name is from Igbo "ọ́nyà", web, snare, trap, and by extension, network. The expanded sense is ọ́nyà úchè, web of knowledge.
+
+# Contributing
+
+Contributions welcome! We're interested in feedback from the community about what works and what doesn't in real-world usage. To get help with the code implementation, read [CONTRIBUTING.md](CONTRIBUTING.md).
+
+# License
+
+- **Code** (Python library): Apache 2.0 - See [LICENSE](LICENSE)
+- **Specification** (wordloom_spec.md): [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/) - See [LICENSE-spec](LICENSE-spec)
+
+The specification is under CC BY 4.0 to encourage broad adoption and derivative work while ensuring attribution. We want the format itself to be as open and reusable as possible, allowing anyone to create implementations in any language or adapt the format for their specific needs.
+
+# Acknowledgments
+
+Created by [Oori Data](https://oori.dev). Word Loom emerged from our work building multilingual LLM applications and finding gaps in existing prompt management approaches.
+
+# Related Work
+
+- [networkx](https://github.com/networkx/networkx): Network Analysis in Python
+- [Apache AGE](https://github.com/apache/incubator-age): PostgreSQL Extension that for graphs. ANSI SQL & openCypher over the same DB.

onya-0.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+onya/__about__.py,sha256=rnObPjuBcEStqSO0S6gsdS_ot8ITOQjVj_-P1LUUYpg,22
+onya/__init__.py,sha256=9uH16tXsn_OEcGbp1pL8uNa5U3Se9AYTxBxNE8WTlFI,553
+onya/graph.py,sha256=qNxVpauro20YRzjiCt5sBf5at47EtOP5VSDRUeCDYeI,5755
+onya/terms.py,sha256=4s-P6qhjMjnCuueJJTsJCX4M3HZxiJxmJ0_MFHDt8i8,303
+onya/version.py,sha256=hQn5JmgQ287WzONNi7gGqb9gJAIwtqbjxNw3UI4od6M,77
+onya/contrib/mkdcomments.py,sha256=nthBD18knhgzlg882qjpWgw9KiiMBOPmtiGLLLRXHDA,2219
+onya/serial/__init__.py,sha256=laeecAq7WK9LHkgqu9Yp3QaW275ts-L36-bX1u6IpI8,58
+onya/serial/literate.py,sha256=CakOQBmNV0MHS4haYppvKJjbKmWS8MTrSyGmTfzCtrk,3209
+onya/serial/literate_lex.py,sha256=FjZIfcF_EJmRGtRKDWJvLzkjsfVeeITAjh4xShcf-T8,20626
+onya/serial/litparse_util.py,sha256=vFondeLB8ZTwcMArrdrZLB9Gy7QkVhDSlB6IJuPVHS8,1608
+onya-0.1.1.dist-info/METADATA,sha256=h0XXT40hclcojhsRAOSMXV41_Kl4Ar3PprG4i6SlRjM,6588
+onya-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+onya-0.1.1.dist-info/licenses/LICENSE-spec,sha256=k56tqgDsUX64EIJo2WC7GbdDIEnnzA_0_gKDfYPHPTw,1386
+onya-0.1.1.dist-info/RECORD,,

onya-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

onya-0.1.1.dist-info/licenses/LICENSE-spec

@@ -0,0 +1,47 @@
+Word Loom Specification License
+
+The Word Loom specification document (wordloom_spec.md) is licensed under the
+Creative Commons Attribution 4.0 International License (CC BY 4.0).
+
+To view a copy of this license, visit:
+https://creativecommons.org/licenses/by/4.0/
+
+or send a letter to:
+Creative Commons
+PO Box 1866
+Mountain View, CA 94042
+USA
+
+---
+
+You are free to:
+
+  * Share — copy and redistribute the specification in any medium or format
+  * Adapt — remix, transform, and build upon the specification for any purpose,
+    even commercially
+
+Under the following terms:
+
+  * Attribution — You must give appropriate credit, provide a link to the
+    license, and indicate if changes were made. You may do so in any reasonable
+    manner, but not in any way that suggests the licensor endorses you or your
+    use.
+
+  * No additional restrictions — You may not apply legal terms or technological
+    measures that legally restrict others from doing anything the license
+    permits.
+
+---
+
+This is a human-readable summary of (and not a substitute for) the full license.
+
+The full legal text of the Creative Commons Attribution 4.0 International
+License is available at:
+https://creativecommons.org/licenses/by/4.0/legalcode
+
+---
+
+Copyright (c) 2023-2025 Oori Data
+
+Attribution example:
+"Based on the Word Loom specification by Oori Data (https://github.com/OoriData/WordLoom)"