totolo 0.1__py2.py3-none-any.whl

totolo/__init__.py

@@ -0,0 +1,15 @@
+"""
+The Python interface to themeontology.org.
+"""
+
+__version__ = "0.1"
+
+from totolo.api import TORemote, empty, files
+
+remote = TORemote()
+
+__ALL__ = [
+    empty,
+    files,
+    remote,
+]

totolo/api.py

@@ -0,0 +1,42 @@
+import json
+import re
+import urllib.request
+
+from .impl.parser import TOParser
+from .themeontology import ThemeOntology
+
+DEFAULT_URL = "https://github.com/theme-ontology/theming/"
+API_URL = "https://api.github.com/repos/theme-ontology/theming/"
+
+
+def files(paths=None):
+    return TOParser.add_files(empty(), paths)
+
+
+def empty():
+    return ThemeOntology()
+
+
+class TORemote:
+    def __call__(self, url: str = "") -> ThemeOntology:
+        if not url:
+            url = DEFAULT_URL + "archive/refs/heads/master.tar.gz"
+        return TOParser.add_url(empty(), url)
+
+    def version(self, version: str = ""):
+        if not version:
+            return self()
+        if re.match(r"v\d+\.\d+\.\d+$", version):
+            url = DEFAULT_URL + f"archive/refs/tags/{version}.tar.gz"
+        elif re.match(r"v20\d{2}\.\d{2}$", version):
+            url = DEFAULT_URL + f"archive/refs/tags/{version}.tar.gz"
+        else:
+            raise ValueError(f"Unknown version format {version}.")
+        return self(url)
+
+    def versions(self):
+        url = API_URL + "releases"
+        with urllib.request.urlopen(url) as response:
+            response.read()
+        for item in json.loads(response.read()):
+            yield item["tag_name"], item["name"]

totolo/impl/core.py

@@ -0,0 +1,92 @@
+from collections import OrderedDict
+from copy import deepcopy
+
+
+class TOAttr:
+    def __init__(self, default="", private=False):
+        self.default = default
+        self.private = private
+
+
+class TOStoredAttr(TOAttr):
+    def __init__(self, datatype="blob", default=None, required=False):
+        if default is None:
+            default = [] if "list" in datatype else ""
+        super().__init__(default, True)
+        self.datatype = datatype
+        self.required = required
+
+
+class TOObjectMeta(type):
+    def __new__(meta, name, bases, attr):
+        to_attrs = OrderedDict()
+        for base in bases:
+            for key, value in getattr(base, "_to_attrs", {}).items():
+                if key not in attr:
+                    to_attrs[key] = value
+        for key, value in list(attr.items()):
+            if isinstance(value, TOStoredAttr):
+                nkey = key.replace("_", " ")
+                to_attrs[nkey] = value
+                del attr[key]
+            elif isinstance(value, TOAttr):
+                to_attrs[key] = value
+                del attr[key]
+        attr["_to_attrs"] = to_attrs
+        return super().__new__(meta, name, bases, attr)
+
+    def __call__(cls, *args, **kwargs):
+        self = super().__call__(*args, **kwargs)
+        for key, value in self._to_attrs.items():
+            if not value.private and not hasattr(self, key):
+                setattr(self, key, deepcopy(value.default))
+        return self
+
+    @classmethod
+    def __prepare__(mcls, _cls, _bases):
+        return OrderedDict()
+
+
+def a(*args, **kwargs):
+    return TOAttr(*args, **kwargs)
+
+
+def sa(*args, **kwargs):
+    return TOStoredAttr(*args, **kwargs)
+
+
+class TOObject(metaclass=TOObjectMeta):
+    def __init__(self, *args, **kwargs):
+        super().__init__()
+        for arg, key in zip(args, self._to_attrs.keys()):
+            setattr(self, key, arg)
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+        self.get_attr = self._to_attrs.get
+
+    def iter_attrs(self):
+        for key, value in self._to_attrs.items():
+            yield key, value
+
+    def iter_stored(self):
+        for key, value in self.iter_attrs():
+            if isinstance(value, TOStoredAttr):
+                yield key, value
+
+    def field_type(self, key):
+        try:
+            return self.get_attr(key).datatype
+        except (KeyError, AttributeError) as _e:
+            return "unknown"
+
+    def field_required(self, key):
+        try:
+            return self.get_attr(key).datatype
+        except (KeyError, AttributeError) as _e:
+            return "unknown"
+
+    def __str__(self):
+        return "[TOObject]"
+
+    def __repr__(self):
+        return f'{type(self).__name__}<{str(self)}>'

totolo/impl/entry.py

@@ -0,0 +1,120 @@
+from collections import OrderedDict
+
+from .core import TOObject, a
+from .field import TOField
+
+
+class TOEntry(TOObject):
+    name = a("")
+    fields = a(OrderedDict())
+    parents = a(set())
+    children = a(set())
+    source = a([])
+    source_location = a("<api>)")
+    ontology = a()
+
+    def __str__(self):
+        return "{}[{}]".format(
+            self.name.encode("ascii", "ignore"),
+            len(self.fields)
+        )
+
+    def __getitem__(self, key):
+        return self.get(key)
+
+    def __setitem__(self, key, value):
+        self.fields[key] = value
+
+    def __delitem__(self, key):
+        del self.fields[key]
+
+    def iter_fields(self, reorder=False, skipunknown=False):
+        if reorder:
+            order = [fn for fn, _ in self.iter_stored()]
+        else:
+            order = self.fields.keys()
+        for fieldname in order:
+            field = self.fields.get(fieldname, None)
+            if field is not None:
+                fieldtype = self.field_type(fieldname)
+                if fieldtype != "unknown" or not skipunknown:
+                    yield field
+
+    def ancestors(self):
+        yield from self._dfs("parents", self._lookup())
+
+    def descendants(self):
+        yield from self._dfs("children", self._lookup())
+
+    def validate(self):
+        junklines = []
+        for idx, line in enumerate(self.source):
+            if idx > 1:
+                if line.startswith("::"):
+                    break
+                elif line.strip():
+                    junklines.append(line)
+        if junklines:
+            junkmsg = '/'.join(junklines)
+            if len(junkmsg) > 13:
+                junkmsg = junkmsg[:10] + "..."
+            yield f"{self.name}: junk in entry header: {junkmsg}"
+        for field in self.fields.values():
+            if self.field_type(field.name) == "unknown":
+                yield f"{self.name}: unknown field '{field.name}'"
+
+    def text_canonical(self):
+        lines = [self.name, "=" * len(self.name), ""]
+        for field in self.iter_fields(reorder=True, skipunknown=True):
+            if self.field_required(field.name) or not field.empty():
+                lines.append(field.text_canonical())
+                lines.append("")
+        return "\n".join(lines)
+
+    def text_original(self):
+        lines = [self.name, "=" * len(self.name), ""]
+        for field in self.iter_fields(reorder=False, skipunknown=False):
+            lines.append(field.text_canonical())
+            lines.append("")
+        return "\n".join(lines)
+
+    def get(self, fieldname):
+        """Get field, returning a frozen default field if it doesn't exist."""
+        field = self.fields.get(fieldname, None)
+        if field is not None:
+            return field
+        fieldtype = self.field_type(fieldname)
+        return TOField(fieldtype=fieldtype, name=fieldname).freeze()
+
+    def setdefault(self, fieldname):
+        """Get field, creating it first if it doesn't exist."""
+        field = self.fields.get(fieldname, None)
+        if field is not None:
+            return field
+        fieldtype = self.field_type(fieldname)
+        field = TOField(fieldtype=fieldtype, name=fieldname)
+        self.fields[fieldname] = field
+        return field
+
+    def delete(self, fieldname):
+        if fieldname in self.fields:
+            del self.fields[fieldname]
+
+    def print(self):
+        print(self.text_canonical().strip())
+
+    def _lookup(self):
+        return {}
+
+    def _dfs(self, attr, lookup):
+        visited = set()
+        pending = [self.name]
+        visited.update(pending)
+        while pending:
+            name = pending.pop()
+            yield name
+            item = lookup[name]
+            for nitem in getattr(item, attr):
+                if nitem not in visited:
+                    pending.append(nitem)
+                    visited.add(nitem)

totolo/impl/field.py

@@ -0,0 +1,109 @@
+from .core import TOObject, a
+from .keyword import TOKeyword
+
+
+class TOField(TOObject):
+    name = a("")
+    fieldtype = a("")
+    source = a([])
+    data = a([])
+    parts = a([])
+    frozen = a(False)
+
+    def __setattr__(self, name, value):
+        if name != "frozen":
+            self.assert_mutable()
+        super().__setattr__(name, value)
+
+    def __repr__(self):
+        return "{}<{}>[{}]".format(
+            type(self).__name__,
+            self.name.encode("ascii", "ignore"),
+            len(self.data)
+        )
+
+    def __str__(self):
+        return self.text_canonical_contents()
+
+    def __iter__(self):
+        for part in self.iter_parts():
+            yield part
+
+    def freeze(self):
+        if not self.frozen:
+            self.source = tuple(self.source)
+            self.data = tuple(self.data)
+            self.parts = tuple(self.parts)
+            self.frozen = True
+        return self
+
+    def assert_mutable(self):
+        if getattr(self, "frozen", False):
+            raise AttributeError(
+                "Object is frozen, indicating it is detached from an ontology.")
+        return True
+
+    def str(self):
+        return str(self)
+
+    def list(self):
+        return list(self.parts)
+
+    def empty(self):
+        return any(self.parts)
+
+    def iter_parts(self):
+        for part in self.parts:
+            yield part
+
+    def text_canonical_contents(self):
+        parts = [str(x) for x in self.iter_parts()]
+        return "\n".join(parts)
+
+    def text_canonical(self):
+        parts = [f":: {self.name}"]
+        parts.extend(str(x) for x in self.iter_parts())
+        return "\n".join(parts)
+
+    def delete_kw(self, kw):
+        """Delete a keyword."""
+        self.assert_mutable()
+        fieldtype = self.fieldtype
+        todelete = set()
+        if fieldtype == "kwlist":
+            for idx, part in enumerate(self.parts):
+                if part.keyword == kw:
+                    todelete.add(idx)
+        self.parts = [p for idx, p in enumerate(self.parts) if idx not in todelete]
+        return min(todelete) if todelete else len(self.parts)
+
+    def update_kw(self, kw, keyword=None, motivation=None, capacity=None, notes=None):
+        """Edit a keyword."""
+        self.assert_mutable()
+        assert self.fieldtype == "kwlist"
+        for part in self.parts:
+            if part.keyword == kw:
+                if keyword is not None:
+                    part.keyword = keyword
+                if motivation is not None:
+                    part.motivation = motivation
+                if capacity is not None:
+                    part.capacity = capacity
+                if notes is not None:
+                    part.notes = notes
+
+    def insert_kw(self, idx=None, keyword="", motivation="", capacity="", notes=""):
+        """Insert a keyword."""
+        self.assert_mutable()
+        assert self.fieldtype == "kwlist"
+        if idx is None:
+            idx = len(self.parts)
+        self.parts.insert(
+            idx,
+            TOKeyword(
+                keyword,
+                capacity=capacity,
+                motivation=motivation,
+                notes=notes
+            )
+        )

totolo/impl/keyword.py

@@ -0,0 +1,14 @@
+from .core import TOObject, a
+
+
+class TOKeyword(TOObject):
+    keyword = a("")
+    capacity = a("")
+    motivation = a("")
+    notes = a("")
+
+    def __str__(self):
+        capacity = f" <{self.capacity}>" if self.capacity else ""
+        motivation = f" [{self.motivation}]" if self.motivation else ""
+        notes = f" {{{self.notes}}}" if self.notes else ""
+        return f"{self.keyword}{capacity}{motivation}{notes}"

totolo/impl/parser.py

@@ -0,0 +1,230 @@
+import os
+import re
+import weakref
+from typing import Generator, Iterable, List, Tuple
+
+import totolo.lib.files
+import totolo.lib.textformat
+
+from ..story import TOStory
+from ..theme import TOTheme
+from .field import TOField
+from .keyword import TOKeyword
+
+
+class TOParser:
+    @staticmethod
+    def iter_entries(lines: Iterable[str]) -> Generator[str, None, None]:
+        """
+        Iterate through the "entries" in a text file. An entry is a block of lines
+        that starts with a title line, followed by a line starting with "===".
+        """
+        linebuffer = []
+        for line in lines:
+            line = line.rstrip()
+            if line.startswith("===") and linebuffer:
+                prevlines = linebuffer[:-1]
+                if any(x for x in prevlines):
+                    yield prevlines
+                linebuffer = [linebuffer[-1]]
+            linebuffer.append(line)
+        if linebuffer and any(line for line in linebuffer):
+            yield linebuffer
+
+    @staticmethod
+    def iter_fields(lines: Iterable[str]) -> List[str]:
+        """
+        Iterate through the fields of an entry. Fields are blocks starting with ::
+        """
+        linebuffer = []
+        for line in lines:
+            if line.startswith("::"):
+                if linebuffer:
+                    yield linebuffer
+                linebuffer = [line]
+            elif linebuffer:
+                linebuffer.append(line)
+        if linebuffer:
+            yield linebuffer
+
+    @staticmethod
+    def iter_listitems(lines: Iterable[str]) -> str:
+        """
+        Turn a list of strings into items. Items may be newline or comma separated.
+        """
+        for line in lines:
+            # note: once upon a time we used to have multiple items separated by commas
+            # on a single line but that is no longer permitted.
+            item = line.strip()
+            if item:
+                yield item
+
+    @staticmethod
+    def iter_kwitems(
+        lines: Iterable[str]
+    ) -> Generator[Tuple[str, str, str, str], None, None]:
+        """
+        Turn a list of strings into kewyword items. Items may be newline or comma
+        separated. Items may contain data in () [] {} parentheses.
+        """
+        def dict2row(tokendict):
+            tkw = tokendict.get("", "").strip()
+            tmotivation = tokendict.get("[", "").strip()
+            tcapacity = tokendict.get("<", "").strip()
+            tnotes = tokendict.get("{", "").strip()
+            return tkw, tcapacity, tmotivation, tnotes
+
+        field = "\n".join(lines)
+        token = {}
+        delcorr = {"[": "]", "{": "}", "<": ">"}
+        farr = re.split("([\\[\\]\\{\\}\\<\\>,\\n])", field)
+        state = ""
+        splitters = ",\n"
+
+        for part in farr:
+            if part in delcorr:
+                state = part
+            elif part in delcorr.values():
+                if delcorr.get(state, None) == part:
+                    state = ""
+                else:
+                    raise AssertionError(
+                        "Malformed field (bracket mismatch):\n  %s" % field
+                    )
+            elif part in splitters and not state:
+                tokrow = dict2row(token)
+                if not tokrow[0].strip():
+                    pass  # we allow splitting by both newline and comma
+                else:
+                    yield tokrow
+                token = {}
+            else:
+                token[state] = token.get(state, "") + part
+
+        tokrow = dict2row(token)
+        if tokrow[0].strip():
+            yield dict2row(token)
+
+    @classmethod
+    def make_field(cls, lines, fieldtype):
+        field = TOField(
+            fieldtype=fieldtype,
+            name=lines[0].strip(": "),
+            data=lines[1:],
+            source=list(lines),
+        )
+        if fieldtype == "kwlist":
+            for kwtuple in TOParser.iter_kwitems(field.data):
+                field.parts.append(TOKeyword(*kwtuple))
+        elif fieldtype == "list":
+            for item in TOParser.iter_listitems(field.data):
+                field.parts.append(item)
+        elif fieldtype == "text":
+            field.parts.append(
+                totolo.lib.textformat.add_wordwrap(
+                    "\n".join(
+                        field.data)).strip())
+        else:
+            field.parts.append('\n'.join(field.data))
+        return field
+
+    @classmethod
+    def populate_entry(cls, entry, lines):
+        entry.source.extend(lines)
+        cleaned = []
+        for line in lines:
+            cline = line.strip()
+            if cline or (cleaned and cleaned[-1]):
+                cleaned.append(cline)  # no more than one blank line in a row
+        assert len(cleaned) > 1 and cleaned[1].startswith("==="), "missing name"
+        while cleaned and not cleaned[-1]:
+            cleaned.pop()
+        entry.name = cleaned[0]
+        for fieldlines in cls.iter_fields(cleaned):
+            while fieldlines and not fieldlines[-1]:
+                fieldlines.pop()
+            name = fieldlines[0].strip(": ")
+            fieldtype = entry.field_type(name)
+            field = cls.make_field(fieldlines, fieldtype)
+            entry[field.name] = field
+        return entry
+
+    @classmethod
+    def make_story(cls, lines):
+        story = cls.populate_entry(TOStory(), lines)
+        return story
+
+    @classmethod
+    def make_theme(cls, lines):
+        theme = cls.populate_entry(TOTheme(), lines)
+        return theme
+
+    @classmethod
+    def parse_stories(cls, lines):
+        collection_entry = None
+        entries = []
+        if isinstance(lines, str):
+            lines = lines.splitlines()
+        for idx, entrylines in enumerate(TOParser.iter_entries(lines)):
+            entry = cls.make_story(entrylines)
+            if idx == 0:
+                mycols = entry.get("Collections").parts
+                if mycols and mycols[0] == entry.sid:
+                    collection_entry = entry
+            if idx > 0 and collection_entry:
+                field = collection_entry.setdefault("Component Stories")
+                field.parts.append(entry.sid)
+            entries.append(entry)
+        return entries
+
+    @classmethod
+    def parse_themes(cls, lines):
+        entries = []
+        if isinstance(lines, str):
+            lines = lines.splitlines()
+        for _idx, entrylines in enumerate(TOParser.iter_entries(lines)):
+            entry = cls.make_theme(entrylines)
+            entries.append(entry)
+        return entries
+
+    @classmethod
+    def add_url(cls, to, url):
+        suffixes = [".tar", ".tar.gz"]
+        if any(url.endswith(x) for x in suffixes):
+            with totolo.lib.files.remote_tar(url) as dirname:
+                cls.add_files(to, dirname)
+        else:
+            raise ValueError(f"Expected url ending in one of {suffixes}")
+        return to
+
+    @classmethod
+    def add_files(cls, to, paths):
+        if isinstance(paths, str):
+            paths = [paths]
+        for path in paths:
+            to.basepaths.add(path)
+            if os.path.isdir(path):
+                for filepath in totolo.lib.files.walk(path, r".*\.(st|th)\.txt$"):
+                    cls._add_file(to, filepath)
+            else:
+                cls._add_file(to, path)
+        return to.refresh_relations()
+
+    @classmethod
+    def _add_file(cls, to, path):
+        target = {}
+        with open(path, "r", encoding='utf-8') as fh:
+            entry_iterable = []
+            if path.endswith(".th.txt"):
+                entry_iterable = cls.parse_themes(fh)
+                target = to.theme
+            elif path.endswith(".st.txt"):
+                entry_iterable = cls.parse_stories(fh)
+                target = to.story
+            for entry in entry_iterable:
+                entry.source_location = path
+                entry.ontology = weakref.ref(to)
+                to.entries.setdefault(path, [])
+                to.entries[path].append(entry)
+                target[entry.name] = entry
+        return to

totolo/lib/files.py

@@ -0,0 +1,38 @@
+import contextlib
+import os
+import os.path
+import re
+import tarfile
+import tempfile
+import urllib.request
+from io import BytesIO
+
+
+@contextlib.contextmanager
+def remote_tar(url: str):
+    with tempfile.TemporaryDirectory() as dirname:
+        with urllib.request.urlopen(url) as response:
+            with tarfile.open(name=None, fileobj=BytesIO(response.read())) as tar:
+                tar.extractall(dirname)
+        paths = [os.path.join(dirname, x) for x in os.listdir(dirname)]
+        # we expect a single (irrelevant) dir here as git wraps everything thus
+        if len(paths) == 1 and os.path.isdir(paths[0]):
+            yield paths[0]
+        else:
+            yield dirname
+
+
+def walk(path: str, pattern: str = ".*", levels: int = -1):
+    r = re.compile(pattern)
+    # yield matching files
+    for item in os.listdir(path):
+        spath = os.path.join(path, item)
+        if r.match(item):
+            if os.path.isfile(spath):
+                yield spath
+    # recurse
+    for item in os.listdir(path):
+        spath = os.path.join(path, item)
+        if os.path.isdir(spath) and levels != 0:
+            for res in walk(spath, pattern, levels - 1):
+                yield res

totolo/lib/textformat.py

@@ -0,0 +1,47 @@
+import textwrap
+
+
+def remove_wordwrap(text):
+    """
+    Remove single newline characters (i.e. '\n') from string, but leave double newlines (i.e. '\n\n').
+    Args:
+        text: string
+    Returns: string
+    """
+    text_blocks = text.split("\n")
+    dewordwraped_text_block = []
+    dewordwraped_text_blocks = []
+
+    for text_block in text_blocks:
+        text_block = text_block.strip()
+
+        if not text_block:
+            if dewordwraped_text_block:
+                dewordwraped_text_blocks.append(" ".join(dewordwraped_text_block))
+            dewordwraped_text_block = []
+        else:
+            dewordwraped_text_block.append(text_block)
+
+    if dewordwraped_text_block:
+        dewordwraped_text_blocks.append(" ".join(dewordwraped_text_block))
+
+    return "\n\n".join(dewordwraped_text_blocks)
+
+def add_wordwrap(text, wrap_length=78):
+    """
+    Add line breaks to string (i.e. '\n' character) so that each line is at most 'wrap_length'
+    characters in length.
+    Args:
+        text: string
+        wrap_length: integer
+    Returns: string
+    """
+    paragraphs = remove_wordwrap(text)
+    wordwrapped_lines = []
+
+    for paragraph in paragraphs.split("\n\n"):
+        for wordwrapped_line in textwrap.fill(paragraph, wrap_length).split("\n"):
+            wordwrapped_lines.append(wordwrapped_line.strip())
+        wordwrapped_lines.append("")
+
+    return "\n".join(wordwrapped_lines)

totolo/story.py

@@ -0,0 +1,128 @@
+import re
+
+from .impl.core import sa
+from .impl.entry import TOEntry
+
+
+class TOStory(TOEntry):
+    Title = sa("text", required=True)
+    Date = sa("date", required=True)
+    Description = sa("text")
+    Authors = sa("blob")
+    Variation = sa("blob")
+    References = sa("list")
+    Ratings = sa("list")
+    Collections = sa("list")
+    Component_Stories = sa("list")
+    Related_Stories = sa("list")
+    Choice_Themes = sa("kwlist")
+    Major_Themes = sa("kwlist")
+    Minor_Themes = sa("kwlist")
+    Not_Themes = sa("kwlist")
+    Other_Keywords = sa("kwlist")
+
+    def iter_theme_entries(self):
+        """
+        Yield (weight, TOKeyword) pairs. TOKeyword contains the comment and other
+        metadata associated with a theme entry in a story.
+        """
+        for weight in ["Choice Themes", "Major Themes", "Minor Themes", "Not Themes"]:
+            field = self.get(weight)
+            if field:
+                for part in field.iter_parts():
+                    yield weight, part
+
+    def iter_themes(self):
+        """
+        Iterate over the theme objects associated with this story object.
+        """
+        if not getattr(self, "ontology", None):
+            raise RuntimeError(
+                "Story must be associated with an ontology to look up themes.")
+        to = self.ontology()
+        for weight, part in self.iter_theme_entries():
+            theme = to.theme[part.keyword]
+            yield weight, theme
+
+    @property
+    def date(self):
+        """
+        Return the date entry as verbatim it is recorded in the text file.
+        """
+        return self.get("Date").text_canonical_contents().strip()
+
+    @property
+    def year(self):
+        """
+        Returns the year of the story, or the earliest year for a collection.
+        A positive number is the year AD.
+        A negative number is the year BC.
+        Zero indicates that the the information is missing (there is no year zero in
+        AD/BC notation). Dates can be entered in a variety of ways but the year should
+        always be present. If this function returns zero for a story the story's data
+        entry is considered to be faulty.
+        """
+        date = self.date
+        yearmatch = re.match("\\d+", date)
+        if not yearmatch:
+            return 0
+        year = int(yearmatch.group())
+        if "bc" in date.lower():
+            year *= -1
+        return year
+
+    @property
+    def sid(self):
+        return self.name
+
+    @property
+    def title(self):
+        return self.get("Title").text_canonical_contents().strip()
+
+    def verbose_description(self):
+        """
+        A description that combines various other fields, including Notes, Examples,
+        Aliases, and References.
+        """
+        description = str(self.get("Description"))
+        references = str(self.get("References")).strip()
+        if references:
+            description += "\n\nReferences:\n"
+            for line in references.split("\n"):
+                line = line.strip()
+                if line:
+                    description += line + "\n"
+        return description
+
+    def html_description(self):
+        """
+        Turn the verbose description into html.
+        """
+        import html
+        description = html.escape(str(self.get("Description")))
+        references = html.escape(str(self.get("References")).strip())
+        description = '<P class="obj-description"><BR>\n' + description
+        description += "</P>\n"
+        if references:
+            description += '<P class="obj-description"><b>References:</b><BR>\n'
+            for line in references.split("\n"):
+                line = line.strip()
+                if line:
+                    aline = '<A href="{}">{}</A>'.format(line, line)
+                    description += aline + "\n"
+            description += "</P>\n"
+        return description
+
+    def html_short_description(self):
+        """
+        A limited length short description without embelishments like "references".
+        """
+        import html
+        description = str(self.get("Description"))[:256]
+        return html.escape(description)
+
+    def _lookup(self):
+        try:
+            return self.ontology().story
+        except AttributeError:
+            return {}

totolo/theme.py

@@ -0,0 +1,71 @@
+from .impl.core import sa
+from .impl.entry import TOEntry
+
+
+class TOTheme(TOEntry):
+    Description = sa("text", required=True)
+    Parents = sa("list")
+    Notes = sa("text")
+    Examples = sa("text")
+    References = sa("list")
+    Aliases = sa("list")
+
+    def verbose_description(self):
+        description = str(self.get("Description"))
+        examples = str(self.get("Examples")).strip()
+        aliases = str(self.get("Aliases")).strip()
+        notes = str(self.get("Notes")).strip()
+        references = str(self.get("References")).strip()
+        if notes:
+            description += "\n\nNotes:\n" + notes
+        if examples:
+            description += "\n\nExamples:\n" + examples
+        if aliases:
+            description += "\n\nAliases:\n" + aliases
+        if references:
+            description += "\n\nReferences:\n"
+            for line in references.split("\n"):
+                line = line.strip()
+                if line:
+                    description += line + "\n"
+        return description
+
+    def html_description(self):
+        import html
+        description = html.escape(str(self.get("Description")))
+        examples = html.escape(str(self.get("Examples")).strip())
+        aliases = html.escape(str(self.get("Aliases")).strip())
+        notes = html.escape(str(self.get("Notes")).strip())
+        references = html.escape(str(self.get("References")).strip())
+        description = '<P class="obj-description"><BR>\n' + description
+        description += "</P>\n"
+        if notes:
+            description += '<P class="obj-description"><b>Notes:</b><BR>\n' + notes
+            description += "</P>\n"
+        if examples:
+            description += '<P class="obj-description"><b>Examples:</b><BR>\n' + examples
+            description += "</P>\n"
+        if aliases:
+            aliases = ', '.join(aliases.split("\n"))
+            description += '<P class="obj-description"><b>Aliases:</b><BR>\n' + aliases
+            description += "</P>\n"
+        if references:
+            description += '<P class="obj-description"><b>References:</b><BR>\n'
+            for line in references.split("\n"):
+                line = line.strip()
+                if line:
+                    aline = '<A href="{}">{}</A>'.format(line, line)
+                    description += aline + "\n"
+            description += "</P>\n"
+        return description
+
+    def html_short_description(self):
+        import html
+        description = str(self.get("Description"))[:256]
+        return html.escape(description)
+
+    def _lookup(self):
+        try:
+            return self.ontology().theme
+        except AttributeError:
+            return {}

totolo/themeontology.py

@@ -0,0 +1,179 @@
+import copy
+import os.path
+import random
+from collections import defaultdict
+
+from .impl.core import TOObject, a
+
+
+class TODict(dict):
+    pass
+
+
+class ThemeOntology(TOObject):
+    theme = a(TODict())
+    story = a(TODict())
+    entries = a({})
+    basepaths = a(set())
+
+    def __len__(self):
+        return sum(len(v) for v in self.entries.values())
+
+    def __str__(self):
+        return f"<{len(self.theme)} themes, {len(self.story)} stories>"
+
+    def stories(self):
+        for story in self.story.values():
+            yield story
+
+    def themes(self):
+        for theme in self.theme.values():
+            yield theme
+
+    def astory(self):
+        return random.sample(self.story.values(), 1)[0]
+
+    def atheme(self):
+        return random.sample(self.theme.values(), 1)[0]
+
+    def dataframe(self, implied_themes=True):
+        import pandas as pd
+        data = []
+        for story in self.stories():
+            for weight, part in story.iter_theme_entries():
+                themes = [part.keyword]
+                if implied_themes and part.keyword in self.theme:
+                    theme = self.theme[part.keyword]
+                    themes.extend(theme.ancestors())
+                data.append([story.name, story["Title"],
+                            story["Date"], part.keyword, weight])
+        return pd.DataFrame(
+            data, columns=["story_id", "title", "date", "theme", "weight"])
+
+    def validate(self):
+        yield from self.validate_entries()
+        yield from self.validate_storythemes()
+        yield from self.validate_cycles()
+
+    def validate_entries(self):
+        """Validate basic format of theme and story entries."""
+        lookup = defaultdict(dict)
+        for path, entries in self.entries.items():
+            for entry in entries:
+                for warning in entry.validate():
+                    yield f"{path}: {warning}"
+                if entry.name in lookup[type(entry)]:
+                    yield f"{path}: Multiple {type(entry)} with name '{entry.name}'"
+
+    def validate_storythemes(self):
+        """Detect undefined themes used in stories."""
+        for story in self.stories():
+            for weight in ["choice", "major", "minor", "not"]:
+                field = f"{weight.capitalize()} Themes"
+                for kwf in story.get(field):
+                    if kwf.keyword not in self.theme:
+                        name, kw = story.name, kwf.keyword
+                        yield f"{name}: Undefined '{weight} theme' with name '{kw}'"
+
+    def validate_cycles(self):
+        """Detect cycles (stops after first cycle encountered)."""
+        parents = {}
+        for theme in self.themes():
+            parents[theme.name] = [parent for parent in theme.get("Parents")]
+
+        def dfs(current, tpath=None):
+            tpath = tpath or []
+            if current in tpath:
+                cycle = tpath[tpath.index(current):]
+                return f"Cycle: {cycle}"
+            else:
+                tpath.append(current)
+                for parent in parents[current]:
+                    msg = dfs(parent, tpath)
+                    if msg:
+                        return msg
+                tpath.pop()
+            return None
+
+        for theme in self.themes():
+            msg = dfs(theme.name)
+            if msg:
+                yield msg
+                break
+
+    def write_clean(self, verbose=False):
+        """
+        Write the ontology back to its source file while cleaning up syntax and
+        omitting unknown field names.
+        """
+        self.write(verbose=verbose)
+
+    def write(self, prefix=None, cleaned=False, verbose=False):
+        old_prefix = "" if prefix is None else os.path.commonpath(self.basepaths)
+        for path, entries in self.entries.items():
+            if prefix is not None:
+                rel_path = os.path.relpath(path, old_prefix)
+                path = os.path.join(prefix, rel_path)
+            self._writefile(path, entries, cleaned)
+            if verbose:
+                print(f"wrote: {path}")
+
+    def print_warnings(self):
+        """
+        Run validate and print warnings to stdout.
+        """
+        for msg in self.validate():
+            print(msg)
+        return self
+
+    def refresh_relations(self):
+        """
+        The ontology keeps track of parent/child relations in order to facilitate
+        quicker traversal of this hierarchy in both directions, for both themes
+        and stories. This method is invoked when the ontology has changed. It is
+        invoked automatically by the parser and usually doesn't need to be invoked
+        manually.
+        """
+        for theme in self.themes():
+            theme.parents.clear()
+            theme.children.clear()
+        for story in self.stories():
+            story.parents.clear()
+            story.children.clear()
+        for theme in self.themes():
+            for ptheme_name in theme["Parents"]:
+                if ptheme_name in self.theme:
+                    theme.parents.add(ptheme_name)
+                    self.theme[ptheme_name].children.add(theme.name)
+        for story in self.stories():
+            for pstory_name in story["Collections"]:
+                if pstory_name in self.story:
+                    story.parents.add(pstory_name)
+                    self.story[pstory_name].children.add(story.name)
+            for cstory_name in story["Component Stories"]:
+                if cstory_name in self.story:
+                    story.children.add(cstory_name)
+                    self.story[cstory_name].parents.add(story.name)
+        return self
+
+    def _writefile(self, path, entries, cleaned):
+        cskey = "Component Stories"
+        dirname = os.path.dirname(path)
+        if not os.path.exists(dirname):
+            os.makedirs(dirname)
+        with open(path, "w", encoding='utf-8') as fh:
+            sids = set(e.name for e in entries)
+            for idx, entry in enumerate(entries):
+                if idx == 0 and entry.name in entry["Collections"]:
+                    field = entry.get(cskey)
+                    parts = [x for x in field.parts if x not in sids]
+                    if parts != field.parts:
+                        entry = copy.deepcopy(entry)
+                        if parts:
+                            field = entry.setdefault(cskey)
+                            field.parts = parts
+                        else:
+                            entry.delete(cskey)
+                lines = entry.text_canonical() if cleaned else entry.text_original()
+                fh.write(lines)
+                fh.write("\n\n")

totolo-0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Theme Ontology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

totolo-0.1.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.1
+Name: totolo
+Version: 0.1
+Summary: The Python interface to themeontology.org.
+Author-email: Mikael Onsjö <mikael@odinlake.net>
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+Project-URL: Documentation, https://github.com/theme-ontology/theming
+Project-URL: Home, https://www.themeontology.org/
+Project-URL: Source, https://github.com/theme-ontology/python-totolo
+
+# python totolo
+
+This repository contains a Python package, totolo,
+for working with data from [the theme repository](https://github.com/theme-ontology/theming/).
+

totolo-0.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+totolo/__init__.py,sha256=lsBiNOLPDdQjpedhdBAwzzyAH5lWE0lfSTURkR6CsfI,189
+totolo/api.py,sha256=Xx63I9PYmL8hxy9NRSQa3rlYqjqBhXMAFCVqnvrFkt4,1247
+totolo/story.py,sha256=NSx36RDe3R8qruXSBYZLYFBBaDBXPjPXmS5xqCz7PQc,4242
+totolo/theme.py,sha256=PxnFINPT4_UDiJElg6GIMHV8ifbKv-oL4WeOgMRgaUo,2665
+totolo/themeontology.py,sha256=CKjghNVbC9yoxm_NQlhkm1jScQ1ugMh5ZEdmWA94Wkg,6588
+totolo/impl/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+totolo/impl/core.py,sha256=QTsdkQBgBQcXFoiO1F3qStBeQMujJ_jKWXjZH5U5VnU,2731
+totolo/impl/entry.py,sha256=kmfm5zbH7yHH0CmnOSu7Jm27atWrCw6xJpOc5XxneRw,3833
+totolo/impl/field.py,sha256=4vub-YUL1bAWxdDCifa1VG-Djfr6aZhTKyeoBxN5PxY,3159
+totolo/impl/keyword.py,sha256=oNRa7-71gAInNMQozW4EfKZhxo2N-RkQWWdx9KM3s7Q,424
+totolo/impl/parser.py,sha256=kKmlrA-vIGVsKmstthYtje1aMCC8trsLCc0YYPfSb6Y,7980
+totolo/lib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+totolo/lib/files.py,sha256=Q-9PESBqoetdJcE0NMUuLJQ_OblOXaDVgpiOPz-vRvk,1192
+totolo/lib/textformat.py,sha256=bv8bmsGIHsqccXSwrTqiPLhMbgRwhhlAEt11oMFDu7M,1408
+totolo-0.1.dist-info/LICENSE,sha256=aQxSEqA2gmQp240XgIJiSZZ_lYvjAk80lmTsdYVl5mY,1071
+totolo-0.1.dist-info/WHEEL,sha256=Sgu64hAMa6g5FdzHxXv9Xdse9yxpGGMeagVtPMWpJQY,99
+totolo-0.1.dist-info/METADATA,sha256=Sd2FDB3i6CC75ZUuQiuonSAwCwPXhTDn4EkkBOAHmhU,595
+totolo-0.1.dist-info/RECORD,,

totolo-0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: flit 3.9.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any