onto-lang 0.1.0__tar.gz

onto_lang-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: onto-lang
+Version: 0.1.0
+Summary: Compact text formats for ontologies, observations and mappings
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+```
+   ▄▄▄▄▄▄▄▄▄    ▄▄▄▄▄▄▄▄▄▄▄    ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄    ▄▄▄▄▄▄▄▄▄
+ ▄▀░▓░      ▀▄  █   ▓░     ▀▄  █     ░▓░     ▓  ▄▀░▓░      ▀▄
+▐▌  ▒        ▐▌ ▓   ▒       ▐▌ █      ▒      ▒ ▐▌  ▒        ▐▌
+█   ░  ░      █ ▒   ░        ▓ █▄▄▄   ░  ▄▄▄▄░ █   ░  ░      █
+█      ▓      █ ░            ▒    █      █     █      ▓      █
+▓      █      █ ░      ░     ░    ▓      █     ▓      █      █
+░      █      ▓ ░      ▒    ░▒    █      █     ░      █      ▓
+▒░     ▓      ▒ ▒░     ▓   ░▒░    ▒░     █     ▒░     ▓      ▒
+▐▓▒░   ▀     ▐▌ ▓▒░   ░█  ░▒▓▒    ░▓▒░   █     ▐▓▒░   ▀     ▐▌
+ ▀▓▒░       ▄▀  █▓▒░  ▒█ ░▒▓█▓    ██▓▒░  █      ▀▓▒░       ▄▀
+   ▀▀▀▀▀▀▀▀▀    ▀▀▀▀▀▀▀▀ ▀▀▀▀▀    ▀▀▀▀▀▀▀▀        ▀▀▀▀▀▀▀▀▀
+```
+
+*onto* is a format (JSON & text) to represent conceptual models (ontologies)
+and instance data (observations), as well the mapping between systems and
+the records they describe.
+
+*onto*'s goal is to:
+- Provide a format to describe data that is compact and expressive
+- Can we read and edited by humans and machines/agents efficiently
+- Facilitate data management and systems integration
+
+Onto is implemented in Python.
+
+Onto offers the following formats, each with a text and a JSON form:
+
+- `.onto` for ontologies ([spec-01](docs/specs/spec-01-ontology.md))
+- `.obs` for observations ([spec-02](docs/specs/spec-02-observations.md))
+- `.bind`, `.map` and `.fn` for bindings, mappings and function libraries
+  ([spec-04](docs/specs/spec-04-mapping.md))
+- `.ref` for identity referentials ([spec-05](docs/specs/spec-05-identities.md))
+
+## Get started
+
+*onto* needs Python 3.14 or later and has no runtime dependencies. The
+distribution is named `onto-lang`; the command and Python import are both
+`onto`.
+
+From the repository root, run the CLI without installing:
+
+```sh
+./bin/onto --help
+```
+
+Or install the checkout into your Python environment:
+
+```sh
+pip install .
+onto --help
+python -m onto --help
+```
+
+The package has not been published to PyPI yet. Once released, you can
+install it with `pip install onto-lang`.
+
+For publishing, see the [release instructions](docs/releasing.md).
+
+## In a nutshell
+
+Files name each other by namespace (`@use Finance as F`), so `onto` indexes
+the files of your project by their header and finds what each one needs:
+
+```
+$ onto ls ontology mapping
+mapping   Exchange->Finance              finance/exchange-finance.map
+ontology  Exchange           2026-11-10  finance/exchange.onto
+ontology  Finance            2026-11-10  finance/finance.onto
+
+$ onto check finance/exchange-finance.map    # loads Exchange, Finance, Markets, MarketIds
+no problems in 1 file (5 read)
+
+$ onto fmt --check                           # lists files whose layout would change
+
+$ onto coverage finance/exchange-finance.map
+source                target                 status       note
+Dividend.Amount       Dividend.Amount        direct
+Dividend.Currency                            condition
+Instrument.Class      Instrument.AssetClass  transformed
+
+$ onto reverse finance/exchange-finance.map > finance-exchange.map
+finance/exchange-finance.map:19: warning map.lossy: ... 'AssetClass' is not
+reversed: @map 'AssetClassFromCode' is not exact and one-to-one
+```
+
+`onto help` lists every command; [spec-07](docs/specs/spec-07-cli.md)
+describes them.

onto_lang-0.1.0/README.md

@@ -0,0 +1,87 @@
+```
+   ▄▄▄▄▄▄▄▄▄    ▄▄▄▄▄▄▄▄▄▄▄    ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄    ▄▄▄▄▄▄▄▄▄
+ ▄▀░▓░      ▀▄  █   ▓░     ▀▄  █     ░▓░     ▓  ▄▀░▓░      ▀▄
+▐▌  ▒        ▐▌ ▓   ▒       ▐▌ █      ▒      ▒ ▐▌  ▒        ▐▌
+█   ░  ░      █ ▒   ░        ▓ █▄▄▄   ░  ▄▄▄▄░ █   ░  ░      █
+█      ▓      █ ░            ▒    █      █     █      ▓      █
+▓      █      █ ░      ░     ░    ▓      █     ▓      █      █
+░      █      ▓ ░      ▒    ░▒    █      █     ░      █      ▓
+▒░     ▓      ▒ ▒░     ▓   ░▒░    ▒░     █     ▒░     ▓      ▒
+▐▓▒░   ▀     ▐▌ ▓▒░   ░█  ░▒▓▒    ░▓▒░   █     ▐▓▒░   ▀     ▐▌
+ ▀▓▒░       ▄▀  █▓▒░  ▒█ ░▒▓█▓    ██▓▒░  █      ▀▓▒░       ▄▀
+   ▀▀▀▀▀▀▀▀▀    ▀▀▀▀▀▀▀▀ ▀▀▀▀▀    ▀▀▀▀▀▀▀▀        ▀▀▀▀▀▀▀▀▀
+```
+
+*onto* is a format (JSON & text) to represent conceptual models (ontologies)
+and instance data (observations), as well the mapping between systems and
+the records they describe.
+
+*onto*'s goal is to:
+- Provide a format to describe data that is compact and expressive
+- Can we read and edited by humans and machines/agents efficiently
+- Facilitate data management and systems integration
+
+Onto is implemented in Python.
+
+Onto offers the following formats, each with a text and a JSON form:
+
+- `.onto` for ontologies ([spec-01](docs/specs/spec-01-ontology.md))
+- `.obs` for observations ([spec-02](docs/specs/spec-02-observations.md))
+- `.bind`, `.map` and `.fn` for bindings, mappings and function libraries
+  ([spec-04](docs/specs/spec-04-mapping.md))
+- `.ref` for identity referentials ([spec-05](docs/specs/spec-05-identities.md))
+
+## Get started
+
+*onto* needs Python 3.14 or later and has no runtime dependencies. The
+distribution is named `onto-lang`; the command and Python import are both
+`onto`.
+
+From the repository root, run the CLI without installing:
+
+```sh
+./bin/onto --help
+```
+
+Or install the checkout into your Python environment:
+
+```sh
+pip install .
+onto --help
+python -m onto --help
+```
+
+The package has not been published to PyPI yet. Once released, you can
+install it with `pip install onto-lang`.
+
+For publishing, see the [release instructions](docs/releasing.md).
+
+## In a nutshell
+
+Files name each other by namespace (`@use Finance as F`), so `onto` indexes
+the files of your project by their header and finds what each one needs:
+
+```
+$ onto ls ontology mapping
+mapping   Exchange->Finance              finance/exchange-finance.map
+ontology  Exchange           2026-11-10  finance/exchange.onto
+ontology  Finance            2026-11-10  finance/finance.onto
+
+$ onto check finance/exchange-finance.map    # loads Exchange, Finance, Markets, MarketIds
+no problems in 1 file (5 read)
+
+$ onto fmt --check                           # lists files whose layout would change
+
+$ onto coverage finance/exchange-finance.map
+source                target                 status       note
+Dividend.Amount       Dividend.Amount        direct
+Dividend.Currency                            condition
+Instrument.Class      Instrument.AssetClass  transformed
+
+$ onto reverse finance/exchange-finance.map > finance-exchange.map
+finance/exchange-finance.map:19: warning map.lossy: ... 'AssetClass' is not
+reversed: @map 'AssetClassFromCode' is not exact and one-to-one
+```
+
+`onto help` lists every command; [spec-07](docs/specs/spec-07-cli.md)
+describes them.

onto_lang-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "onto-lang"
+version = "0.1.0"
+description = "Compact text formats for ontologies, observations and mappings"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = []
+
+[project.scripts]
+onto = "onto.main:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "jsonschema>=4.18"]
+
+[tool.setuptools]
+package-dir = { "" = "src/py" }
+
+[tool.setuptools.packages.find]
+where = ["src/py"]
+include = ["onto*"]
+
+[tool.pytest.ini_options]
+python_files = ["T*.py"]
+addopts = "--import-mode=importlib"
+testpaths = ["tests"]
+# NOTE: The optional hexa integration is tested against the sibling checkout when present.
+pythonpath = ["src/py", "../hexa/src/py"]

onto_lang-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

onto_lang-0.1.0/src/py/onto/__init__.py

@@ -0,0 +1,215 @@
+"""Module: onto — ontology/observation formats, mapping declarations and identity policies."""
+
+from __future__ import annotations
+
+from .text import Diagnostic, FormatError, Source
+from .ontology import (
+	Operator as OntologyOperator,
+	Model,
+	Ontology,
+	formatOntology,
+	loadOntology,
+	normaliseOntology,
+	ontologyFromJson,
+	ontologyToJson,
+	parseOntology,
+	printOntology,
+	validateOntology,
+)
+from .observations import (
+	Operator as ObservationsOperator,
+	Gap,
+	Observations,
+	ObservationsDocument,
+	formatObservations,
+	loadObservations,
+	observationsFromJson,
+	observationsToJson,
+	parseObservations,
+	printObservationsLog,
+	printObservationsState,
+	reconcileObservations,
+	resolveObservations,
+)
+from .coverage import CoverageItem, CoverageReport, CoverageRow, observationsCoverage, printCoverageTable
+from .expressions import Expression, expressionFromJson, parseExpression, printExpression
+from .functions import (
+	Operator as FunctionsOperator,
+	Function,
+	FunctionDeclaration,
+	FunctionEvaluator,
+	FunctionExample,
+	FunctionLibrary,
+	FunctionResult,
+	FunctionsDocument,
+	SignatureType,
+	formatFunctions,
+	functionsFromJson,
+	functionsToJson,
+	loadFunctions,
+	parseFunctions,
+	printFunctions,
+	resolveFunctions,
+)
+from .binding import (
+	Operator as BindingOperator,
+	Binding,
+	BindingDocument,
+	BindingExclusion,
+	BindingLine,
+	BindingScope,
+	bindingFromJson,
+	bindingToJson,
+	formatBinding,
+	loadBinding,
+	parseBinding,
+	printBinding,
+	resolveBinding,
+	bindingCoverage,
+)
+from .mapping import (
+	Operator as MappingOperator,
+	Mapping,
+	MappingDocument,
+	MappingExclusion,
+	MappingLine,
+	MappingScope,
+	formatMapping,
+	loadMapping,
+	mappingFromJson,
+	mappingToJson,
+	parseMapping,
+	printMapping,
+	resolveMapping,
+	LossyLine,
+	mappingCoverage,
+	mappingReverse,
+)
+from .inventory import Inventory, InventoryField, defaultBinding, documentFields, inventoryFromDocuments, parseInventory, printInventory
+from .formats import FormatChange, Formats, FormatsEntry, formatsUpdate, parseFormats, printFormats
+from .referential import (
+	Operator as ReferentialOperator,
+	Policy as ReferentialPolicy,
+	Referential,
+	formatReferential,
+	loadReferential,
+	parseReferential,
+	printReferential,
+	referentialFromJson,
+	referentialImplicit,
+	referentialPolicy,
+	referentialToJson,
+	validateReferential,
+)
+
+__all__ = [
+	"Binding",
+	"BindingDocument",
+	"BindingExclusion",
+	"BindingLine",
+	"BindingScope",
+	"BindingOperator",
+	"CoverageItem",
+	"CoverageReport",
+	"CoverageRow",
+	"FormatChange",
+	"Formats",
+	"FormatsEntry",
+	"Inventory",
+	"InventoryField",
+	"LossyLine",
+	"Diagnostic",
+	"Expression",
+	"FormatError",
+	"Function",
+	"FunctionDeclaration",
+	"FunctionEvaluator",
+	"FunctionExample",
+	"FunctionLibrary",
+	"FunctionResult",
+	"FunctionsDocument",
+	"FunctionsOperator",
+	"Gap",
+	"Model",
+	"Mapping",
+	"MappingDocument",
+	"MappingExclusion",
+	"MappingLine",
+	"MappingScope",
+	"MappingOperator",
+	"Ontology",
+	"OntologyOperator",
+	"Observations",
+	"ObservationsDocument",
+	"ObservationsOperator",
+	"Referential",
+	"ReferentialOperator",
+	"ReferentialPolicy",
+	"Source",
+	"SignatureType",
+	"expressionFromJson",
+	"bindingFromJson",
+	"bindingToJson",
+	"formatBinding",
+	"formatOntology",
+	"formatObservations",
+	"formatFunctions",
+	"formatMapping",
+	"formatReferential",
+	"functionsFromJson",
+	"functionsToJson",
+	"loadOntology",
+	"loadObservations",
+	"loadFunctions",
+	"loadBinding",
+	"loadMapping",
+	"loadReferential",
+	"mappingFromJson",
+	"mappingToJson",
+	"normaliseOntology",
+	"ontologyFromJson",
+	"ontologyToJson",
+	"observationsFromJson",
+	"observationsCoverage",
+	"observationsToJson",
+	"parseOntology",
+	"parseExpression",
+	"parseFunctions",
+	"parseBinding",
+	"parseMapping",
+	"parseReferential",
+	"parseObservations",
+	"printOntology",
+	"printExpression",
+	"printFunctions",
+	"printBinding",
+	"printMapping",
+	"printReferential",
+	"printObservationsLog",
+	"printObservationsState",
+	"reconcileObservations",
+	"referentialFromJson",
+	"referentialImplicit",
+	"referentialPolicy",
+	"referentialToJson",
+	"resolveObservations",
+	"resolveFunctions",
+	"resolveBinding",
+	"resolveMapping",
+	"validateOntology",
+	"validateReferential",
+	"bindingCoverage",
+	"defaultBinding",
+	"documentFields",
+	"formatsUpdate",
+	"inventoryFromDocuments",
+	"mappingCoverage",
+	"mappingReverse",
+	"parseFormats",
+	"parseInventory",
+	"printCoverageTable",
+	"printFormats",
+	"printInventory",
+]
+
+# EOF

onto_lang-0.1.0/src/py/onto/__main__.py

@@ -0,0 +1,12 @@
+"""Module: __main__ — run the `onto` command line with `python -m onto`."""
+
+from __future__ import annotations
+
+import sys
+
+from .main import main
+
+if __name__ == "__main__":
+	sys.exit(main())
+
+# EOF

onto_lang-0.1.0/src/py/onto/binding/__init__.py

@@ -0,0 +1,19 @@
+"""Module: binding — spec-04 binding declarations and interchange, without execution."""
+
+from __future__ import annotations
+
+from .model import Binding, BindingDocument, BindingExclusion, BindingLine, BindingScope, Condition
+from .parser import parseBinding
+from .formatter import bindingToJson, printBinding
+from .operations import Operator, bindingFromJson, formatBinding, loadBinding, resolveBinding
+from .coverage import bindingCoverage
+
+BindingOperator = Operator
+
+__all__ = [
+	"Binding", "BindingDocument", "BindingExclusion", "BindingLine", "BindingScope", "Condition", "Operator", "BindingOperator",
+	"parseBinding", "resolveBinding", "loadBinding", "formatBinding", "printBinding", "bindingToJson", "bindingFromJson",
+	"bindingCoverage",
+]
+
+# EOF

onto_lang-0.1.0/src/py/onto/binding/coverage.py

@@ -0,0 +1,174 @@
+"""Module: binding.coverage — static coverage of a binding: ontology side and document side (spec-04)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..coverage import CoverageReport, CoverageRow, Elements, coverageRows
+from ..expressions import Expression, printExpression
+from ..inventory.model import CONTAINER_TYPES, Inventory
+from ..ontology.model import Model, Ontology
+from .model import Binding, BindingScope
+
+# -----------------------------------------------------------------------------
+#
+# DEFINITIONS
+#
+# -----------------------------------------------------------------------------
+
+
+type Steps = list[Any]
+
+EACH = {"each": True}
+
+
+# -----------------------------------------------------------------------------
+#
+# UTILITIES
+#
+# -----------------------------------------------------------------------------
+
+
+def documentPaths(expr: Expression | None) -> list[Steps]:
+	"""Document paths an expression reads; the type argument of `ref` is not one."""
+	if expr is None:
+		return []
+	if "path" in expr:
+		return [expr["path"]]
+	if "call" in expr:
+		args = expr["args"][1:] if expr["call"] == "ref" else expr["args"]
+		return [path for arg in args for path in documentPaths(arg)]
+	if "coalesce" in expr:
+		return [path for item in expr["coalesce"] for path in documentPaths(item)]
+	return []
+
+
+def absolute(scope: Steps | None, steps: Steps) -> Steps:
+	"""Steps of a path read from a record at `scope`, from the document root, indexes as `[*]`.
+
+	`^` climbs to the enclosing list element; `$` restarts at the root. A JSON root
+	object is implicit (`asOf`); a root list keeps its `$[*]`.
+	"""
+	first = steps[0] if steps else None
+	if isinstance(first, dict) and "root" in first:
+		base, steps = [], steps[1:]
+	elif isinstance(first, dict) and "up" in first:
+		eaches = [index for index, step in enumerate(scope or []) if step == EACH]
+		count = first["up"]
+		base = list(scope[:eaches[-1 - count] + 1]) if len(eaches) > count else []
+		steps = steps[1:]
+	else:
+		base = list(scope or [])
+	result = base + [EACH if isinstance(step, dict) and "index" in step else step for step in steps]
+	if result and isinstance(result[0], dict) and "root" in result[0] and (len(result) < 2 or result[1] != EACH):
+		result = result[1:]
+	if not result:
+		return []
+	if result[0] == EACH:
+		result = [{"root": True}] + result
+	return result
+
+
+def pathText(steps: Steps) -> str:
+	return printExpression({"path": steps}, binding=True) if steps else "$"
+
+
+# -----------------------------------------------------------------------------
+#
+# OPERATIONS
+#
+# -----------------------------------------------------------------------------
+
+
+class BindingCoverage:
+	"""Collect the fields each scope reads and the elements its lines assign."""
+
+	def __init__(self, ontology: Ontology, binding: Binding):
+		self.binding = binding
+		self.elements = Elements(Model(ontology), binding.ontology)
+		self.reads: dict[str, list[tuple[str | None, str, str | None]]] = {}
+		self.assigned: set[str] = set()
+
+	def record(self, scope: Steps | None, paths: list[Steps], target: str | None, status: str, note: str | None = None) -> None:
+		for steps in paths:
+			path = absolute(scope, steps)
+			if path:
+				self.reads.setdefault(pathText(path), []).append((target, status, note))
+
+	def enclosing(self, scope: BindingScope, up: int) -> BindingScope | None:
+		"""The scope line whose records enclose this scope's, `up` lists above."""
+		steps = absolute(None, scope.path["path"])
+		eaches = [index for index, step in enumerate(steps) if step == EACH]
+		if len(eaches) <= up:
+			return None
+		prefix = steps[:eaches[-1 - up] + 1]
+		return next((item for item in self.binding.scopes if absolute(None, item.path["path"]) == prefix), None)
+
+	def scope(self, scope: BindingScope) -> None:
+		steps = absolute(None, scope.path["path"])
+		typeName = self.elements.display(scope.type)
+		self.record(None, [scope.path["path"]], typeName, "direct", scope.doc)
+		conditions = documentPaths(scope.id) + documentPaths(scope.valid) + documentPaths(scope.ctx)
+		conditions += [scope.deleted["path"]] if scope.deleted else []
+		self.record(steps, conditions, None, "condition")
+		for line in scope.lines:
+			key = self.elements.assigned(scope.type, line.target, line.facet, line.verb)
+			if key:
+				self.assigned.add(key)
+			member = f"[{line.facet}]" if line.facet else f".{line.target or line.verb}"
+			expr = line.expr
+			if expr is not None and "path" in expr and len(expr["path"]) == 1 and isinstance(expr["path"][0], dict) and "up" in expr["path"][0]:
+				# `^` reads the enclosing record's key.
+				parent = self.enclosing(scope, expr["path"][0]["up"])
+				if parent is not None:
+					self.record(absolute(None, parent.path["path"]), documentPaths(parent.id), None, "condition")
+				continue
+			status = "direct" if expr is not None and "path" in expr else "transformed"
+			self.record(steps, documentPaths(expr), typeName + member, status, line.doc)
+			if line.when:
+				self.record(steps, [line.when["path"]], None, "condition")
+
+	def report(self, inventory: Inventory | None) -> CoverageReport:
+		if self.binding.at is not None:
+			self.record(None, documentPaths(self.binding.at), None, "condition")
+		for scope in self.binding.scopes:
+			self.scope(scope)
+		keys = [key for decl in self.elements.instanceTypes() for key in self.elements.declared(decl.path)]
+		keys += [f"{decl.path}.{decl.arrow.verb}" for decl in self.elements.model.ontology.decls if decl.kind == "relation" and decl.arrow and f"{decl.participants[0].type}.{decl.arrow.verb}" not in keys]
+		unassigned = sorted(self.elements.display(key) for key in dict.fromkeys(keys)
+			if key not in self.assigned and not any(key.startswith(item + ".") for item in self.assigned))
+		if inventory is None:
+			return CoverageReport([], unassigned, [])
+		types = inventory.types()
+		excluded: dict[str, tuple[str, str | None]] = {}
+		for exclusion in self.binding.exclusions:
+			prefix = pathText(absolute(None, exclusion.path["path"]))
+			for path in types:
+				if path == prefix or path.startswith(prefix + ".") or path.startswith(prefix + "["):
+					excluded.setdefault(path, (exclusion.reason, exclusion.doc))
+		# NOTE: Containers (objects, lists) are reported only when read or excluded themselves; their fields carry the rest.
+		fields = [path for path, kind in types.items() if kind not in CONTAINER_TYPES or path in self.reads or path in excluded]
+		rows: list[CoverageRow] = coverageRows(fields, self.reads, excluded)
+		return CoverageReport(rows, unassigned, sorted(path for path in self.reads if path not in types and path != "$"))
+
+
+# -----------------------------------------------------------------------------
+#
+# HIGH-LEVEL API
+#
+# -----------------------------------------------------------------------------
+
+
+def bindingCoverage(ontology: Ontology, binding: Binding, inventory: Inventory | None = None) -> CoverageReport:
+	"""Both sides of a binding's coverage.
+
+	`unassigned` is the ontology side: elements no line assigns, needing no data. With an
+	`inventory`, `rows` give each document field's status and `uninventoried` the paths
+	the binding reads that the inventory does not list.
+	"""
+	return BindingCoverage(ontology, binding).report(inventory)
+
+
+__all__ = ["bindingCoverage", "absolute", "documentPaths"]
+
+# EOF