Python: improves documentation

1 year ago · 4c97637e4b
parent a6f32390df
commit 4c97637e4b
4 changed files with 29 additions and 24 deletions
--- 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'<foo> <p> "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'<http://example.com> <http://example.com/p> "1" .\n'
--- 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 <https://tools.ietf.org/rfc/rfc3987>`_.
 ///
-/// 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'))
 /// '<http://example.com>'
@ -135,11 +135,11 @@ impl PyNamedNode {

 /// An RDF `blank node <https://www.w3.org/TR/rdf11-concepts/#dfn-blank-node>`_.
 ///
-/// :param value: the `blank node ID <https://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier>`_ (if not present, a random blank node ID is automatically generated).
+/// :param value: the `blank node identifier <https://www.w3.org/TR/rdf11-concepts/#dfn-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 <https://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier>`_.
+    /// :return: the `blank node identifier <https://www.w3.org/TR/rdf11-concepts/#dfn-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 <https://tools.ietf.org/rfc/rfc5646>`_ (`BCP 47 <https://tools.ietf.org/rfc/bcp/bcp47>`_).
 ///
-/// 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<PyObject> 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')))
 /// '<http://example.com> <http://example.com/p> "1"'
@ -801,7 +801,7 @@ impl IntoPy<PyObject> 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')))
 /// '<http://example.com> <http://example.com/p> "1" <http://example.com/g>'
@ -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'
--- 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 <https://www.w3.org/TR/sparql11-results-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 <https://www.w3.org/TR/sparql11-results-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 <https://www.w3.org/TR/turtle/>`_
    /// and ``application/xml`` or ``xml`` for `RDF/XML <https://www.w3.org/TR/rdf-syntax-grammar/>`_.
    ///
-    /// :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<http://example.com/s>\t<http://example.com/s>\t1\n')
 /// >>> list(parse_query_results(input, "text/tsv"))
--- 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'<foo> <p> "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'<foo> <p> "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 <https://www.w3.org/TR/turtle/>`_
    /// and ``application/xml`` or ``xml`` for `RDF/XML <https://www.w3.org/TR/rdf-syntax-grammar/>`_.
    ///
-    /// :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.