From 4c97637e4b8abc651f545cd5e8b80ebeba0f58c4 Mon Sep 17 00:00:00 2001 From: Tpt Date: Tue, 12 Sep 2023 21:34:12 +0200 Subject: [PATCH] Python: improves documentation --- python/src/io.rs | 9 ++++++--- python/src/model.rs | 18 +++++++++--------- python/src/sparql.rs | 15 ++++++++------- python/src/store.rs | 11 ++++++----- 4 files changed, 29 insertions(+), 24 deletions(-) diff --git a/python/src/io.rs b/python/src/io.rs index 9a88ec9a..be494e22 100644 --- a/python/src/io.rs +++ b/python/src/io.rs @@ -36,14 +36,15 @@ use std::path::{Path, PathBuf}; /// :type format: str or None, optional /// :param base_iri: the base IRI used to resolve the relative IRIs in the file or :py:const:`None` if relative IRI resolution should not be done. /// :type base_iri: str or None, optional -/// :param without_named_graphs: Sets that the parser must fail if parsing a named graph. +/// :param without_named_graphs: Sets that the parser must fail when parsing a named graph. /// :type without_named_graphs: bool, optional -/// :param rename_blank_nodes: Renames the blank nodes ids from the ones set in the serialization to random ids. This allows to avoid id conflicts when merging graphs together. +/// :param rename_blank_nodes: Renames the blank nodes identifiers from the ones set in the serialization to random ids. This allows to avoid identifier conflicts when merging graphs together. /// :type rename_blank_nodes: bool, optional /// :return: an iterator of RDF triples or quads depending on the format. /// :rtype: iterator(Quad) /// :raises ValueError: if the format is not supported. /// :raises SyntaxError: if the provided data is invalid. +/// :raises OSError: if a system error happens while reading the file. /// /// >>> input = io.BytesIO(b'

"1" .') /// >>> list(parse(input, "text/turtle", base_iri="http://example.com/")) @@ -101,13 +102,15 @@ pub fn parse( /// /// :param input: the RDF triples and quads to serialize. /// :type input: iterable(Triple) or iterable(Quad) -/// :param output: The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with ``open('my_file.ttl', 'wb')``. If :py:const:`None`, a :py:func:`bytes` buffer is returned with the serialized content. +/// :param output: The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with ``open('my_file.ttl', 'wb')``. If :py:const:`None`, a :py:class:`bytes` buffer is returned with the serialized content. /// :type output: io(bytes) or str or pathlib.Path or None, optional /// :param format: the format of the RDF serialization using a media type like ``text/turtle`` or an extension like `ttl`. If :py:const:`None`, the format is guessed from the file name extension. /// :type format: str or None, optional +/// :return: py:class:`bytes` with the serialization if the ``output`` parameter is :py:const:`None`, :py:const:`None` if ``output`` is set. /// :rtype: bytes or None /// :raises ValueError: if the format is not supported. /// :raises TypeError: if a triple is given during a quad format serialization or reverse. +/// :raises OSError: if a system error happens while writing the file. /// /// >>> serialize([Triple(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1'))], format="ttl") /// b' "1" .\n' diff --git a/python/src/model.rs b/python/src/model.rs index e2694c61..61f327a4 100644 --- a/python/src/model.rs +++ b/python/src/model.rs @@ -16,7 +16,7 @@ use std::vec::IntoIter; /// :type value: str /// :raises ValueError: if the IRI is not valid according to `RFC 3987 `_. /// -/// The :py:func:`str` function provides a serialization compatible with NTriples, Turtle, and SPARQL: +/// The :py:class:`str` function provides a serialization compatible with NTriples, Turtle, and SPARQL: /// /// >>> str(NamedNode('http://example.com')) /// '' @@ -135,11 +135,11 @@ impl PyNamedNode { /// An RDF `blank node `_. /// -/// :param value: the `blank node ID `_ (if not present, a random blank node ID is automatically generated). +/// :param value: the `blank node identifier `_ (if not present, a random blank node identifier is automatically generated). /// :type value: str or None, optional -/// :raises ValueError: if the blank node ID is invalid according to NTriples, Turtle, and SPARQL grammars. +/// :raises ValueError: if the blank node identifier is invalid according to NTriples, Turtle, and SPARQL grammars. /// -/// The :py:func:`str` function provides a serialization compatible with NTriples, Turtle, and SPARQL: +/// The :py:class:`str` function provides a serialization compatible with NTriples, Turtle, and SPARQL: /// /// >>> str(BlankNode('ex')) /// '_:ex' @@ -198,7 +198,7 @@ impl PyBlankNode { .into()) } - /// :return: the `blank node ID `_. + /// :return: the `blank node identifier `_. /// :rtype: str /// /// >>> BlankNode("ex").value @@ -270,7 +270,7 @@ impl PyBlankNode { /// :type language: str or None, optional /// :raises ValueError: if the language tag is not valid according to `RFC 5646 `_ (`BCP 47 `_). /// -/// The :py:func:`str` function provides a serialization compatible with NTriples, Turtle, and SPARQL: +/// The :py:class:`str` function provides a serialization compatible with NTriples, Turtle, and SPARQL: /// /// >>> str(Literal('example')) /// '"example"' @@ -606,7 +606,7 @@ impl IntoPy for PyTerm { /// :param object: the triple object. /// :type object: NamedNode or BlankNode or Literal or Triple /// -/// The :py:func:`str` function provides a serialization compatible with NTriples, Turtle, and SPARQL: +/// The :py:class:`str` function provides a serialization compatible with NTriples, Turtle, and SPARQL: /// /// >>> str(Triple(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1'))) /// ' "1"' @@ -801,7 +801,7 @@ impl IntoPy for PyGraphName { /// :param graph_name: the quad graph name. If not present, the default graph is assumed. /// :type graph_name: NamedNode or BlankNode or DefaultGraph or None, optional /// -/// The :py:func:`str` function provides a serialization compatible with NTriples, Turtle, and SPARQL: +/// The :py:class:`str` function provides a serialization compatible with NTriples, Turtle, and SPARQL: /// /// >>> str(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1'), NamedNode('http://example.com/g'))) /// ' "1" ' @@ -995,7 +995,7 @@ impl PyQuad { /// :type value: str /// :raises ValueError: if the variable name is invalid according to the SPARQL grammar. /// -/// The :py:func:`str` function provides a serialization compatible with SPARQL: +/// The :py:class:`str` function provides a serialization compatible with SPARQL: /// /// >>> str(Variable('foo')) /// '?foo' diff --git a/python/src/sparql.rs b/python/src/sparql.rs index 039c2628..ef544e2d 100644 --- a/python/src/sparql.rs +++ b/python/src/sparql.rs @@ -224,13 +224,13 @@ impl PyQuerySolutions { /// It supports also some media type and extension aliases. /// For example, ``application/json`` could also be used for `JSON `_. /// - /// :param output: The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with ``open('my_file.ttl', 'wb')``. If :py:const:`None`, a :py:func:`bytes` buffer is returned with the serialized content. + /// :param output: The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with ``open('my_file.ttl', 'wb')``. If :py:const:`None`, a :py:class:`bytes` buffer is returned with the serialized content. /// :type output: io(bytes) or str or pathlib.Path or None, optional /// :param format: the format of the query results serialization using a media type like ``text/csv`` or an extension like `csv`. If :py:const:`None`, the format is guessed from the file name extension. /// :type format: str or None, optional /// :rtype: bytes or None /// :raises ValueError: if the format is not supported. - /// :raises OSError: if an error happens during a file writing. + /// :raises OSError: if a system error happens while writing the file. /// /// >>> store = Store() /// >>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1'))) @@ -325,13 +325,13 @@ impl PyQueryBoolean { /// It supports also some media type and extension aliases. /// For example, ``application/json`` could also be used for `JSON `_. /// - /// :param output: The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with ``open('my_file.ttl', 'wb')``. If :py:const:`None`, a :py:func:`bytes` buffer is returned with the serialized content. + /// :param output: The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with ``open('my_file.ttl', 'wb')``. If :py:const:`None`, a :py:class:`bytes` buffer is returned with the serialized content. /// :type output: io(bytes) or str or pathlib.Path or None, optional /// :param format: the format of the query results serialization using a media type like ``text/csv`` or an extension like `csv`. If :py:const:`None`, the format is guessed from the file name extension. /// :type format: str or None, optional /// :rtype: bytes or None /// :raises ValueError: if the format is not supported. - /// :raises OSError: if an error happens during a file writing. + /// :raises OSError: if a system error happens while writing the file. /// /// >>> store = Store() /// >>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1'))) @@ -404,13 +404,13 @@ impl PyQueryTriples { /// For example, ``application/turtle`` could also be used for `Turtle `_ /// and ``application/xml`` or ``xml`` for `RDF/XML `_. /// - /// :param output: The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with ``open('my_file.ttl', 'wb')``. If :py:const:`None`, a :py:func:`bytes` buffer is returned with the serialized content. + /// :param output: The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with ``open('my_file.ttl', 'wb')``. If :py:const:`None`, a :py:class:`bytes` buffer is returned with the serialized content. /// :type output: io(bytes) or str or pathlib.Path or None, optional /// :param format: the format of the RDF serialization using a media type like ``text/turtle`` or an extension like `ttl`. If :py:const:`None`, the format is guessed from the file name extension. /// :type format: str or None, optional /// :rtype: bytes or None /// :raises ValueError: if the format is not supported. - /// :raises OSError: if an error happens during a file writing. + /// :raises OSError: if a system error happens while writing the file. /// /// >>> store = Store() /// >>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1'))) @@ -468,10 +468,11 @@ impl PyQueryTriples { /// :type input: io(bytes) or io(str) or str or pathlib.Path /// :param format: the format of the RDF serialization using a media type like ``text/turtle`` or an extension like `ttl`. If :py:const:`None`, the format is guessed from the file name extension. /// :type format: str or None, optional -/// :return: an iterator of :py:class:`QuerySolution` or a :py:func:`bool`. +/// :return: an iterator of :py:class:`QuerySolution` or a :py:class:`bool`. /// :rtype: QuerySolutions or QueryBoolean /// :raises ValueError: if the format is not supported. /// :raises SyntaxError: if the provided data is invalid. +/// :raises OSError: if a system error happens while reading the file. /// /// >>> input = io.BytesIO(b'?s\t?p\t?o\n\t\t1\n') /// >>> list(parse_query_results(input, "text/tsv")) diff --git a/python/src/store.rs b/python/src/store.rs index 874e48aa..1befc92a 100644 --- a/python/src/store.rs +++ b/python/src/store.rs @@ -33,7 +33,7 @@ use std::path::PathBuf; /// :type path: str or pathlib.Path or None, optional /// :raises OSError: if the target directory contains invalid data or could not be accessed. /// -/// The :py:func:`str` function provides a serialization of the store in NQuads: +/// The :py:class:`str` function provides a serialization of the store in NQuads: /// /// >>> store = Store() /// >>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1'), NamedNode('http://example.com/g'))) @@ -251,7 +251,7 @@ impl PyStore { /// :type default_graph: NamedNode or BlankNode or DefaultGraph or list(NamedNode or BlankNode or DefaultGraph) or None, optional /// :param named_graphs: list of the named graphs that could be used in SPARQL `GRAPH` clause. By default, all the store named graphs are available. /// :type named_graphs: list(NamedNode or BlankNode) or None, optional - /// :return: a :py:func:`bool` for ``ASK`` queries, an iterator of :py:class:`Triple` for ``CONSTRUCT`` and ``DESCRIBE`` queries and an iterator of :py:class:`QuerySolution` for ``SELECT`` queries. + /// :return: a :py:class:`bool` for ``ASK`` queries, an iterator of :py:class:`Triple` for ``CONSTRUCT`` and ``DESCRIBE`` queries and an iterator of :py:class:`QuerySolution` for ``SELECT`` queries. /// :rtype: QuerySolutions or QueryBoolean or QueryTriples /// :raises SyntaxError: if the provided query is invalid. /// :raises OSError: if an error happens while reading the store. @@ -373,7 +373,7 @@ impl PyStore { /// :rtype: None /// :raises ValueError: if the format is not supported. /// :raises SyntaxError: if the provided data is invalid. - /// :raises OSError: if an error happens during a quad insertion. + /// :raises OSError: if an error happens during a quad insertion or if a system error happens while reading the file. /// /// >>> store = Store() /// >>> store.load(io.BytesIO(b'

"1" .'), "text/turtle", base_iri="http://example.com/", to_graph=NamedNode("http://example.com/g")) @@ -442,7 +442,7 @@ impl PyStore { /// :rtype: None /// :raises ValueError: if the format is not supported. /// :raises SyntaxError: if the provided data is invalid. - /// :raises OSError: if an error happens during a quad insertion. + /// :raises OSError: if an error happens during a quad insertion or if a system error happens while reading the file. /// /// >>> store = Store() /// >>> store.bulk_load(io.BytesIO(b'

"1" .'), "text/turtle", base_iri="http://example.com/", to_graph=NamedNode("http://example.com/g")) @@ -498,12 +498,13 @@ impl PyStore { /// For example, ``application/turtle`` could also be used for `Turtle `_ /// and ``application/xml`` or ``xml`` for `RDF/XML `_. /// - /// :param output: The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with ``open('my_file.ttl', 'wb')``. If :py:const:`None`, a :py:func:`bytes` buffer is returned with the serialized content. + /// :param output: The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with ``open('my_file.ttl', 'wb')``. If :py:const:`None`, a :py:class:`bytes` buffer is returned with the serialized content. /// :type output: io(bytes) or str or pathlib.Path or None, optional /// :param format: the format of the RDF serialization using a media type like ``text/turtle`` or an extension like `ttl`. If :py:const:`None`, the format is guessed from the file name extension. /// :type format: str or None, optional /// :param from_graph: the store graph from which dump the triples. Required if the serialization format does not support named graphs. If it does supports named graphs the full dataset is written. /// :type from_graph: NamedNode or BlankNode or DefaultGraph or None, optional + /// :return: py:class:`bytes` with the serialization if the ``output`` parameter is :py:const:`None`, :py:const:`None` if ``output`` is set. /// :rtype: bytes or None /// :raises ValueError: if the format is not supported or the `from_graph` parameter is not given with a syntax not supporting named graphs. /// :raises OSError: if an error happens during a quad lookup or file writing.