sbol3.document ============== .. py:module:: sbol3.document Classes ------- .. autoapisummary:: sbol3.document.Document Functions --------- .. autoapisummary:: sbol3.document.copy sbol3.document.data_path Module Contents --------------- .. py:class:: Document .. py:method:: __contains__(item) .. py:method:: __iter__() Iterate over the top level objects in this document. >>> import sbol3 >>> doc = sbol3.Document() >>> doc.read('some_path.ttl') >>> for top_level in doc: >>> print(top_level.identity) :return: An iterator over the top level objects .. py:method:: __len__() Get the total number of objects in the Document. (Returns the same thing as size()) :return: The total number of objects in the Document. .. py:method:: __str__() Produce a string representation of the Document. :return: A string representation of the Document. .. py:method:: accept(visitor: Any) -> Any Invokes `visit_document` on `visitor` with `self` as the only argument. :param visitor: The visitor instance :type visitor: Any :raises AttributeError: If visitor lacks a visit_document method :return: Whatever `visitor.visit_document` returns :rtype: Any .. py:method:: add(objects: Union[TopLevel, Sequence[TopLevel]]) -> Union[TopLevel, Sequence[TopLevel]] .. py:method:: addNamespace(namespace: str, prefix: str) -> None Document.addNamespace is deprecated. Replace with Document.bind. Document.addNamespace existed in pySBOL2 and was commonly used. Document.addNamespace(namespace, prefix) should now be Document.bind(prefix, namespace). Note the change of argument order. .. py:method:: bind(prefix: str, uri: str) -> None Bind a prefix to an RDF namespace in the written RDF document. These prefixes make the written RDF easier for humans to read. These prefixes do not change the semantic meaning of the RDF document in any way. .. py:method:: builder(type_uri: str) -> Callable[[str, str], Identified] Lookup up the builder callable for the given type_uri. The builder must have been previously registered under this type_uri via Document.register_builder(). :raises: ValueError if the type_uri does not have an associated builder. .. py:method:: change_object_namespace(top_levels: Iterable[TopLevel], new_namespace: str, update_references: Iterable[TopLevel] = None) -> Any :staticmethod: Change the namespace of all TopLevel objects in `top_levels` to new_namespace, regardless of the previous value, while maintaining referential integrity among all the top level objects in top_levels, including their dependents. The namespace change is "in place". No new objects are allocated. Note: this operation can result in an invalid Document if the change in namespace creates a naming collision. This method does not check for this case either before or after the operation. It is up to the caller to decide whether this operation is safe. :param top_levels: objects to change :param new_namespace: new namespace for objects :param update_references: objects that should have their references updated without changing their namespace :return: Nothing .. py:method:: clear() -> None .. py:method:: clone() -> List[TopLevel] Clone the top level objects in this document. :return: A list of cloned TopLevel objects .. py:method:: copy() -> Document Make a copy of this document. :return: A new document containing a new set of objects that are identical to the original objects. .. py:method:: file_extension(file_format: str) -> str :staticmethod: Return standard extensions when provided the document's file format :param file_format: The format of the file :return: A file extension, including the leading '.' .. py:method:: find(search_string: str) -> Optional[Identified] Find an object by identity URI or by display_id. :param search_string: Either an identity URI or a display_id :type search_string: str :returns: The named object or ``None`` if no object was found .. py:method:: find_all(predicate: Callable[[Identified], bool]) -> List[Identified] Executes a predicate on every object in the document tree, gathering the list of objects to which the predicate returns true. .. py:method:: graph() -> rdflib.Graph Convert document to an RDF Graph. The returned graph is a snapshot of the document and will not be updated by subsequent changes to the document. .. py:method:: join_lines(lines: List[Union[bytes, str]]) -> Union[bytes, str] Join lines for either bytes or strings. Joins a list of lines together whether they are bytes or strings. Returns a bytes if the input was a list of bytes, and a str if the input was a list of str. .. py:attribute:: logger .. py:method:: migrate(top_levels: Iterable[TopLevel]) -> Any Migrate objects to this document. No effort is made to maintain referential integrity. The burden of referential integrity lies with the caller of this method. :param top_levels: The top levels to migrate to this document :return: Nothing .. py:attribute:: objects :type: List[TopLevel] :value: [] .. py:method:: open(location: Union[pathlib.Path, str], file_format: str = None) -> Document :staticmethod: .. py:attribute:: orphans :type: List[Identified] :value: [] .. py:method:: parse_shacl_graph(shacl_graph: rdflib.Graph, report: ValidationReport) -> ValidationReport Convert SHACL violations and warnings into a pySBOL3 validation report. :param shacl_graph: The output graph from pyshacl :type shacl_graph: rdflib.Graph :param report: The ValidationReport to be populated :type report: ValidationReport :return: report :rtype: ValidationReport .. py:method:: read(location: Union[pathlib.Path, str], file_format: str = None) -> None .. py:method:: read_string(data: str, file_format: str) -> None .. py:method:: register_builder(type_uri: str, builder: Callable[[str, str], Identified]) -> None :staticmethod: A builder function will be called with an identity and a keyword argument type_uri. builder(identity_uri: str, type_uri: str = None) -> SBOLObject .. py:method:: remove(objects: Iterable[TopLevel]) .. py:method:: remove_object(top_level: TopLevel) Removes the given TopLevel from this document. No referential integrity is updated, and the TopLevel object is not informed that it has been removed, so it may still have a pointer to this document. No errors are raised and no value is returned. N.B. You probably want to use `remove` instead of `remove_object`. :param top_level: An object to remove :return: Nothing .. py:method:: size() Get the total number of objects in the Document. :return: The total number of objects in the Document. .. py:method:: summary() Produce a string representation of the Document. :return: A string representation of the Document. .. py:method:: traverse(func: Callable[[Identified], None]) Enable a traversal of the entire object hierarchy contained in this document. .. py:method:: validate(report: ValidationReport = None) -> ValidationReport Validate all objects in this document. .. py:method:: validate_shacl(report: Optional[ValidationReport] = None) -> ValidationReport Validate this document using SHACL rules. .. py:method:: write(fpath: Union[pathlib.Path, str], file_format: str = None) -> None Write the document to file. If file_format is None the desired format is guessed from the extension of fpath. If file_format cannot be guessed a ValueError is raised. .. py:method:: write_string(file_format: str) -> str .. py:function:: copy(top_levels: Iterable[TopLevel], into_namespace: Optional[str] = None, into_document: Optional[Document] = None) -> List[TopLevel] Copy SBOL objects, optionally changing their namespace and optionally adding them to a document. Referential integrity among the group of provided TopLevel objects is maintained. If `new_namespace` is provided, the newly created objects will have the provided namespace and will maintain the rest of their identities, including the local path and diplay ID. If `new_document` is provided, the newly created objects will be added to the provided Document. :param top_levels: Top Level objects to be copied :param into_namespace: A namespace to be given to the new objects :param into_document: A document to which the newly created objects will be added :return: A list of the newly created objects .. py:function:: data_path(path: str) -> str Expand path based on module installation directory. :param path: :return: