pyjelly 0.7.1__cp311-cp311-macosx_11_0_x86_64.whl

pyjelly/_proto/grpc.proto

@@ -0,0 +1,33 @@
+syntax = "proto3";
+package eu.ostrzyciel.jelly.core.proto.v1;
+
+// Jelly gRPC streaming protocol.
+// Specification document: https://w3id.org/jelly/1.0.0/specification/streaming
+// Protocol version: 1.0.0
+
+import "rdf.proto";
+
+// Subscribe command sent by the client to the server.
+message RdfStreamSubscribe {
+  // The topic to which the client wants to subscribe (UTF-8 encoded).
+  string topic = 1;
+  // Optional: the stream options requested by the client.
+  // The server should respond with a stream that matches these options.
+  // In case that is not possible, the server must respond with the
+  // INVALID_ARGUMENT error.
+  RdfStreamOptions requested_options = 2;
+}
+
+// Acknowledgement of receiving a stream sent by the server to the client.
+message RdfStreamReceived {
+}
+
+// Pub/Sub service for RDF streams, to be implemented by the server.
+service RdfStreamService {
+  // Subscribe to an RDF stream.
+  rpc SubscribeRdf (RdfStreamSubscribe) returns (stream RdfStreamFrame);
+  // Publish an RDF stream.
+  // In case the server cannot process the stream, it must respond with
+  // the INVALID_ARGUMENT error.
+  rpc PublishRdf (stream RdfStreamFrame) returns (RdfStreamReceived);
+}

pyjelly/_proto/patch.proto

@@ -0,0 +1,165 @@
+syntax = "proto3";
+package eu.ostrzyciel.jelly.core.proto.v1.patch;
+
+// EXPERIMENTAL FEATURE -- the API and format may change.
+
+// RDF Patch implementation based on Jelly
+// RDF Patch spec: https://afs.github.io/rdf-delta/rdf-patch.html
+// Jelly-Patch spec: https://w3id.org/jelly/1.1.0/specification/patch
+
+import "rdf.proto";
+
+message RdfPatchTransactionStart {
+}
+
+message RdfPatchTransactionCommit {
+}
+
+message RdfPatchTransactionAbort {
+}
+
+message RdfPatchNamespace {
+  // Short name of the namespace (e.g., "ex")
+  // Do NOT include the colon.
+  string name = 1;
+  // IRI of the namespace (e.g., "http://example.org/").
+  // Optional in the "prefix delete" (PD) operation,
+  // but required in the "prefix add" (PA) operation.
+  RdfIri value = 2;
+  // Graph name for the namespace declaration.
+  //
+  // This is required for the statement type QUADS, and disallowed for
+  // the statement type TRIPLES.
+  //
+  // This is used to achieve full 1:1 replication in systems that associate
+  // namespaces with specific graphs (e.g., Apache Jena).
+  //
+  // Repeated term compression IS supported for this field.
+  // The repeated terms are shared between the namespace and statement rows.
+  oneof graph {
+    // IRI
+    RdfIri           g_iri = 3;
+    // Blank node
+    string           g_bnode = 4;
+    // Default graph
+    RdfDefaultGraph  g_default_graph = 5;
+    // Literal – only valid for generalized RDF streams
+    RdfLiteral       g_literal = 6;
+  }
+}
+
+// Metadata header for RDF Patch.
+// Header rows must occur at the start of the patch frame.
+message RdfPatchHeader {
+  // Header key (required)
+  string key = 1;
+  // Header value (required)
+  // Repeated term compression is not supported for header values.
+  // This oneof must always be set to a valid RDF term.
+  oneof value {
+    // IRI
+    RdfIri        h_iri = 2;
+    // Blank node
+    string        h_bnode = 3;
+    // Literal
+    RdfLiteral    h_literal = 4;
+    // RDF-star quoted triple
+    RdfTriple     h_triple_term = 5;
+  }
+}
+
+message RdfPatchPunctuation {
+}
+
+// RDF Patch stream options
+message RdfPatchOptions {
+  // Type of statements in the stream (required)
+  PatchStatementType statement_type = 1;
+  // Type of the stream (required)
+  PatchStreamType stream_type = 2;
+  // Whether the stream may contain generalized triples, quads, or datasets
+  bool generalized_statements = 3;
+  // Whether the stream may contain RDF-star statements
+  bool rdf_star = 4;
+  // Maximum size of the name lookup table
+  // (required, must be >= 8)
+  uint32 max_name_table_size = 9;
+  // Maximum size of the prefix lookup table
+  // (required if the prefix lookup is used)
+  uint32 max_prefix_table_size = 10;
+  // Maximum size of the datatype lookup table
+  // (required if datatype literals are used)
+  uint32 max_datatype_table_size = 11;
+  // Protocol version (required)
+  // For Jelly-Patch 1.0.x (based on Jelly-RDF 1.1.x), the value must be 1.
+  // For custom extensions, the value must be 10000 or higher.
+  uint32 version = 15;
+}
+
+// Type of statements in the stream.
+// This determines whether the statements are interpreted as triples or quads.
+enum PatchStatementType {
+  // Unspecified stream type – invalid
+  PATCH_STATEMENT_TYPE_UNSPECIFIED = 0;
+  // RDF triples
+  PATCH_STATEMENT_TYPE_TRIPLES = 1;
+  // RDF quads
+  PATCH_STATEMENT_TYPE_QUADS = 2;
+}
+
+// Type of the stream.
+// This determines whether each RdfPatchFrame is a complete patch by itself,
+// or part of a larger patch.
+enum PatchStreamType {
+  // Unspecified stream type – invalid
+  PATCH_STREAM_TYPE_UNSPECIFIED = 0;
+  // Each RdfPatchFrame is a complete patch.
+  // In this case, transactions cannot span multiple frames.
+  PATCH_STREAM_TYPE_FRAME = 1;
+  // Entire stream is a single patch.
+  // Transactions may span multiple frames.
+  PATCH_STREAM_TYPE_FLAT = 2;
+  // Stream contains multiple patches separated by punctuation marks.
+  // Patches and transactions may span multiple frames.
+  // Each frame must contain at most one patch.
+  PATCH_STREAM_TYPE_PUNCTUATED = 3;
+}
+
+// A row in an RDF Patch stream
+message RdfPatchRow {
+  oneof row {
+    // Stream options. Must be the first row in the stream.
+    RdfPatchOptions options = 1;
+    // Add a triple/quad statement (A)
+    RdfQuad statement_add = 2;
+    // Delete a triple/quad statement (D)
+    RdfQuad statement_delete = 3;
+    // Add a namespace/prefix declaration (PA)
+    RdfPatchNamespace namespace_add = 4;
+    // Delete a namespace/prefix declaration (PD)
+    RdfPatchNamespace namespace_delete = 5;
+    // Transaction start (TX)
+    RdfPatchTransactionStart transaction_start = 6;
+    // Transaction commit (TC)
+    RdfPatchTransactionCommit transaction_commit = 7;
+    // Transaction abort (TA)
+    RdfPatchTransactionAbort transaction_abort = 8;
+    // Entry in the name lookup table.
+    RdfNameEntry name = 11;
+    // Entry in the prefix lookup table.
+    RdfPrefixEntry prefix = 12;
+    // Entry in the datatype lookup table.
+    RdfDatatypeEntry datatype = 13;
+    // Header entry (H)
+    RdfPatchHeader header = 14;
+    // Punctuation mark, only used in stream type PUNCTUATED
+    // Indicates the end of a patch.
+    RdfPatchPunctuation punctuation = 15;
+  }
+}
+
+// A batch of RDF patch rows.
+message RdfPatchFrame {
+  // Patch rows
+  repeated RdfPatchRow rows = 1;
+}

pyjelly/_proto/rdf.proto

@@ -0,0 +1,384 @@
+syntax = "proto3";
+package eu.ostrzyciel.jelly.core.proto.v1;
+
+// Jelly RDF serialization with Protocol Buffers.
+// Specification document: 
+// https://w3id.org/jelly/1.1.1/specification/serialization
+// Protocol version: 1.1.1
+
+// RDF IRIs
+// The IRIs are reconstructed by the consumer using the prefix and name
+// lookup tables.
+message RdfIri {
+  // 1-based, refers to an entry in the prefix lookup.
+  //
+  // 0 signifies "use the same prefix_id as in the previous IRI".
+  // For this to work, IRIs must be processed strictly in order: firstly by
+  // stream row, then by term (subject, predicate, object, graph). This also
+  // applies recursively to RDF-star quoted triples.
+  //
+  // If 0 appears in the first IRI of the stream (and in any subsequent IRI),
+  // this should be interpreted as an empty ("") prefix. This is for example
+  // used when the prefix lookup table is disabled.
+  uint32 prefix_id = 1;
+
+  // 1-based, refers to an entry in the name lookup.
+  //
+  // 0 signifies "use the previous name_id + 1". This requires the same order
+  // guarantees as prefixes.
+  //
+  // If 0 appears in the first IRI of the stream, it should be interpreted as
+  // name_id = 1.
+  uint32 name_id = 2;
+}
+
+// RDF literals
+message RdfLiteral {
+  // The lexical form of the literal (required).
+  string lex = 1;
+
+  // Literal kind – at most one of these field may be set.
+  // If none is set, then it's a simple literal.
+  oneof literalKind {
+    // Language-tagged string.
+    string langtag = 2;
+    // Typed literal. The datatype is a reference to an entry in the
+    // datatype lookup. This value is 1-based and the value of 0
+    // is invalid (in contrast to prefix_id and name_id in RdfIri).
+    uint32 datatype = 3;
+  }
+}
+
+// Empty message indicating the default RDF graph.
+message RdfDefaultGraph {
+}
+
+// RDF triple
+//
+// For each term (subject, predicate, object), the fields are repeated for
+// performance reasons. This is to avoid the need for boxing each term in a
+// separate message.
+//
+// Note: this message allows for representing generalized RDF triples (for
+// example, with literals as predicates). Whether this is used in the stream
+// is determined by the stream options (see RdfStreamOptions).
+//
+// If no field in a given oneof is set, the term is interpreted as a repeated
+// term – the same as the term in the same position in the previous triple.
+// In the first triple of the stream, all terms must be set.
+// All terms must also be set in quoted triples (RDF-star).
+message RdfTriple {
+  // Triple subject
+  oneof subject {
+    // IRI
+    RdfIri        s_iri = 1;
+    // Blank node
+    string        s_bnode = 2;
+    // Literal
+    // Only valid in a generalized RDF stream.
+    RdfLiteral    s_literal = 3;
+    // RDF-star quoted triple
+    RdfTriple     s_triple_term = 4;
+  }
+
+  // Triple predicate
+  oneof predicate {
+    // IRI
+    RdfIri        p_iri = 5;
+    // Blank node
+    // Only valid in a generalized RDF stream.
+    string        p_bnode = 6;
+    // Literal
+    // Only valid in a generalized RDF stream.
+    RdfLiteral    p_literal = 7;
+    // RDF-star quoted triple
+    RdfTriple     p_triple_term = 8;
+  }
+
+  // Triple object
+  oneof object {
+    // IRI
+    RdfIri        o_iri = 9;
+    // Blank node
+    string        o_bnode = 10;
+    // Literal
+    RdfLiteral    o_literal = 11;
+    // RDF-star quoted triple
+    RdfTriple     o_triple_term = 12;
+  }
+}
+
+// RDF quad
+//
+// Fields 1–12 are repeated from RdfTriple for performance reasons.
+//
+// Similarly to RdfTriple, this message allows for representing generalized
+// RDF quads (for example, with literals as predicates). Whether this is used
+// in the stream is determined by the stream options (see RdfStreamOptions).
+//
+// If no field in a given oneof is set, the term is interpreted as a repeated
+// term – the same as the term in the same position in the previous quad.
+// In the first quad of the stream, all terms must be set.
+message RdfQuad {
+  // Quad subject
+  oneof subject {
+    // IRI
+    RdfIri        s_iri = 1;
+    // Blank node
+    string        s_bnode = 2;
+    // Literal
+    // Only valid in a generalized RDF stream.
+    RdfLiteral    s_literal = 3;
+    // RDF-star quoted triple
+    RdfTriple     s_triple_term = 4;
+  }
+
+  // Quad predicate
+  oneof predicate {
+    // IRI
+    RdfIri        p_iri = 5;
+    // Blank node
+    // Only valid in a generalized RDF stream.
+    string        p_bnode = 6;
+    // Literal
+    // Only valid in a generalized RDF stream.
+    RdfLiteral    p_literal = 7;
+    // RDF-star quoted triple
+    RdfTriple     p_triple_term = 8;
+  }
+
+  // Quad object
+  oneof object {
+    // IRI
+    RdfIri        o_iri = 9;
+    // Blank node
+    string        o_bnode = 10;
+    // Literal
+    RdfLiteral    o_literal = 11;
+    // RDF-star quoted triple
+    RdfTriple     o_triple_term = 12;
+  }
+
+  // Quad graph
+  oneof graph {
+    // IRI
+    RdfIri           g_iri = 13;
+    // Blank node
+    string           g_bnode = 14;
+    // Default graph
+    RdfDefaultGraph  g_default_graph = 15;
+    // Literal – only valid for generalized RDF streams
+    RdfLiteral       g_literal = 16;
+  }
+}
+
+// Start of a graph in a GRAPHS stream
+//
+// In contrast to RdfQuad, setting the graph oneof to some value
+// is always required. No repeated terms are allowed.
+message RdfGraphStart {
+  oneof graph {
+    // IRI
+    RdfIri           g_iri = 1;
+    // Blank node
+    string           g_bnode = 2;
+    // Default graph
+    RdfDefaultGraph  g_default_graph = 3;
+    // Literal – only valid for generalized RDF streams
+    RdfLiteral       g_literal = 4;
+  }
+}
+
+// End of a graph in a GRAPHS stream
+message RdfGraphEnd {
+}
+
+// Explicit namespace declaration
+//
+// This does not correspond to any construct in the RDF Abstract Syntax.
+// Rather, it is a hint to the consumer that the given IRI prefix (namespace)
+// may be associated with a shorter name, like in Turtle syntax:
+// PREFIX ex: <http://example.org/>
+//
+// These short names (here "ex:") are NOT used in the RDF statement encoding.
+// This is a purely cosmetic feature useful in cases where you want to
+// preserve the namespace declarations from the original RDF document.
+// These declarations have nothing in common with the prefix lookup table.
+message RdfNamespaceDeclaration {
+  // Short name of the namespace (e.g., "ex")
+  // Do NOT include the colon.
+  string name = 1;
+  // IRI of the namespace (e.g., "http://example.org/")
+  RdfIri value = 2;
+}
+
+// Entry in the name lookup table
+message RdfNameEntry {
+  // 1-based identifier
+  // If id=0, it should be interpreted as previous_id + 1.
+  // If id=0 appears in the first RdfNameEntry of the stream, it should be
+  // interpreted as 1.
+  uint32 id = 1;
+  // Value of the name (UTF-8 encoded)
+  string value = 2;
+}
+
+// Entry in the prefix lookup table
+//
+// Note: the prefixes in the lookup table can be arbitrary strings, and are
+// NOT meant to be user-facing. They are only used for IRI compression.
+// To transmit user-facing namespace declarations for cosmetic purposes, use
+// RdfNamespaceDeclaration.
+message RdfPrefixEntry {
+  // 1-based identifier
+  // If id=0, it should be interpreted as previous_id + 1.
+  // If id=0 appears in the first RdfPrefixEntry of the stream, it should be
+  // interpreted as 1.
+  uint32 id = 1;
+  // Value of the prefix (UTF-8 encoded)
+  string value = 2;
+}
+
+// Entry in the datatype lookup table
+message RdfDatatypeEntry {
+  // 1-based identifier
+  // If id=0, it should be interpreted as previous_id + 1.
+  // If id=0 appears in the first RdfDatatypeEntry of the stream, it should be
+  // interpreted as 1.
+  uint32 id = 1;
+  // Value of the datatype (UTF-8 encoded)
+  string value = 2;
+}
+
+// RDF stream options
+message RdfStreamOptions {
+  // Name of the stream (completely optional).
+  // This may be used for, e.g., topic names in a pub/sub system.
+  string stream_name = 1;
+  // Type of the stream (required)
+  PhysicalStreamType physical_type = 2;
+  // Whether the stream may contain generalized triples, quads, or datasets
+  bool generalized_statements = 3;
+  // Whether the stream may contain RDF-star statements
+  bool rdf_star = 4;
+  // Maximum size of the name lookup table
+  // (required, must be >= 8)
+  uint32 max_name_table_size = 9;
+  // Maximum size of the prefix lookup table
+  // (required if the prefix lookup is used)
+  uint32 max_prefix_table_size = 10;
+  // Maximum size of the datatype lookup table 
+  // (required if datatype literals are used)
+  uint32 max_datatype_table_size = 11;
+  // Logical (RDF-STaX-based) stream type
+  // In contrast to the physical type, this field is entirely optional.
+  LogicalStreamType logical_type = 14;
+  // Protocol version (required)
+  // For Jelly 1.0.x value must be 1.
+  // For Jelly 1.1.x value must be 2.
+  // For custom extensions, the value must be 10000 or higher.
+  uint32 version = 15;
+}
+
+// Physical stream type
+// This determines how the data is encoded in the stream, not the logical
+// structure of the data. See LogicalStreamType for the latter.
+enum PhysicalStreamType {
+  // Unspecified stream type – invalid
+  PHYSICAL_STREAM_TYPE_UNSPECIFIED = 0;
+  // RDF triples
+  PHYSICAL_STREAM_TYPE_TRIPLES = 1;
+  // RDF quads
+  PHYSICAL_STREAM_TYPE_QUADS = 2;
+  // RDF triples grouped in graphs
+  PHYSICAL_STREAM_TYPE_GRAPHS = 3;
+}
+
+// Logical stream type, according to the RDF Stream Taxonomy (RDF-STaX).
+// Type 0 is reserved for the unspecified stream type.
+// The rest of the type numbers follow the taxonomical structure of RDF-STaX.
+// For example: 1 is a subtype of 0, 13 and 23 are subtypes of 3, 
+// 114 is a subtype of 14, etc.
+// 
+// Types 1–4 correspond to the four base concrete stream types. Their 
+// subtypes can be in most cases simply processed in the same way as 
+// the base types.
+// Therefore, implementations can take the modulo 10 of the stream 
+// type to determine the base type of the stream and use this information 
+// to select the appropriate processing logic.
+//
+// RDF-STaX version: 1.1.2
+// https://w3id.org/stax/1.1.2
+//
+// ^ The above URL is used to automatically determine the version of RDF-STaX
+// in the Jelly protocol specification. Please keep it up-to-date and in the
+// same format.
+enum LogicalStreamType {
+  // Unspecified stream type – invalid
+  LOGICAL_STREAM_TYPE_UNSPECIFIED = 0;
+  // Flat RDF triple stream
+  // https://w3id.org/stax/ontology#flatTripleStream
+  LOGICAL_STREAM_TYPE_FLAT_TRIPLES = 1;
+  // Flat RDF quad stream
+  // https://w3id.org/stax/ontology#flatQuadStream
+  LOGICAL_STREAM_TYPE_FLAT_QUADS = 2;
+  // RDF graph stream
+  // https://w3id.org/stax/ontology#graphStream
+  LOGICAL_STREAM_TYPE_GRAPHS = 3;
+  // RDF dataset stream
+  // https://w3id.org/stax/ontology#datasetStream
+  LOGICAL_STREAM_TYPE_DATASETS = 4;
+
+  // RDF subject graph stream (subtype of RDF graph stream)
+  // https://w3id.org/stax/ontology#subjectGraphStream
+  LOGICAL_STREAM_TYPE_SUBJECT_GRAPHS = 13;
+
+  // RDF named graph stream (subtype of RDF dataset stream)
+  // https://w3id.org/stax/ontology#namedGraphStream
+  LOGICAL_STREAM_TYPE_NAMED_GRAPHS = 14;
+  // RDF timestamped named graph stream (subtype of RDF dataset stream)
+  // https://w3id.org/stax/ontology#timestampedNamedGraphStream
+  LOGICAL_STREAM_TYPE_TIMESTAMPED_NAMED_GRAPHS = 114;
+}
+
+// RDF stream row
+message RdfStreamRow {
+  // Exactly one of these fields must be set.
+  oneof row {
+    // Stream options. Must occur at the start of the stream.
+    RdfStreamOptions options = 1;
+    // RDF triple statement.
+    // Valid in streams of physical type TRIPLES or GRAPHS.
+    RdfTriple triple = 2;
+    // RDF quad statement.
+    // Only valid in streams of physical type QUADS.
+    RdfQuad quad = 3;
+    // Graph boundary: ends the currently transmitted graph and starts a new one
+    // Only valid in streams of physical type GRAPHS.
+    RdfGraphStart graph_start = 4;
+    // Explicit end of a graph.
+    // Signals the consumer that the transmitted graph is complete.
+    // Only valid in streams of physical type GRAPHS.
+    RdfGraphEnd graph_end = 5;
+    // Explicit namespace declaration.
+    RdfNamespaceDeclaration namespace = 6;
+    // Entry in the name lookup table.
+    RdfNameEntry name = 9;
+    // Entry in the prefix lookup table.
+    RdfPrefixEntry prefix = 10;
+    // Entry in the datatype lookup table.
+    RdfDatatypeEntry datatype = 11;
+  }
+}
+
+// RDF stream frame – base message for RDF streams.
+message RdfStreamFrame {
+  // Stream rows
+  repeated RdfStreamRow rows = 1;
+  // Arbitrary metadata
+  // The keys are UTF-8 encoded strings, the values are byte arrays.
+  // This may be used by implementations in any way they see fit.
+  // The metadata does not affect the RDF data in any way, treat it
+  // as comments in a text file.
+  map<string, bytes> metadata = 15;
+}

pyjelly/errors.py

@@ -0,0 +1,10 @@
+class JellyConformanceError(Exception):
+    """Raised when Jelly conformance is violated."""
+
+
+class JellyAssertionError(AssertionError):
+    """Raised when a recommended assertion from the specification fails."""
+
+
+class JellyNotImplementedError(NotImplementedError):
+    """Raised when a future feature is not yet implemented."""