sbol3.document

Module Contents

Classes

Document

Functions

copy(→ List[TopLevel])

Copy SBOL objects, optionally changing their namespace and

data_path(→ str)

Expand path based on module installation directory.
class Document
__contains__(item)
__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)
Returns

An iterator over the top level objects

__len__()

Get the total number of objects in the Document.

(Returns the same thing as size())

Returns

The total number of objects in the Document.

__str__()

Produce a string representation of the Document.

Returns

A string representation of the Document.

accept(visitor: Any) → Any

Invokes visit_document on visitor with self as the only argument.

Parameters

visitor (Any) – The visitor instance

Raises

AttributeError – If visitor lacks a visit_document method

Returns

Whatever visitor.visit_document returns

Return type

Any

add(objects: Union[TopLevel, Sequence[TopLevel]]) → Union[TopLevel, Sequence[TopLevel]]
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.

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.

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.

static change_object_namespace(top_levels: Iterable[TopLevel], new_namespace: str, update_references: Iterable[TopLevel] = None) → Any

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.

Parameters

  • top_levels – objects to change

  • new_namespace – new namespace for objects

  • update_references – objects that should have their references updated without changing their namespace

Returns

Nothing

clear() → None
clone() → List[TopLevel]

Clone the top level objects in this document.

Returns

A list of cloned TopLevel objects

copy() → Document

Make a copy of this document.

Returns

A new document containing a new set of objects that are identical to the original objects.

static file_extension(file_format: str) → str

Return standard extensions when provided the document’s file format

Parameters

file_format – The format of the file

Returns

A file extension, including the leading ‘.’

find(search_string: str) → Optional[Identified]

Find an object by identity URI or by display_id.

Parameters

search_string (str) – Either an identity URI or a display_id

Returns

The named object or None if no object was found

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.

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.

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.

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.

Parameters

top_levels – The top levels to migrate to this document

Returns

Nothing

static open(location: Union[pathlib.Path, str], file_format: str = None) → Document
parse_shacl_graph(shacl_graph: rdflib.Graph, report: ValidationReport) → ValidationReport

Convert SHACL violations and warnings into a pySBOL3 validation report.

Parameters

  • shacl_graph (rdflib.Graph) – The output graph from pyshacl

  • report (ValidationReport) – The ValidationReport to be populated

Returns

report

Return type

ValidationReport

read(location: Union[pathlib.Path, str], file_format: str = None) → None
read_string(data: str, file_format: str) → None
static register_builder(type_uri: str, builder: Callable[[str, str], Identified]) → None

A builder function will be called with an identity and a keyword argument type_uri.

builder(identity_uri: str, type_uri: str = None) -> SBOLObject

remove(objects: Iterable[TopLevel])
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.

Parameters

top_level – An object to remove

Returns

Nothing

size()

Get the total number of objects in the Document.

Returns

The total number of objects in the Document.

summary()

Produce a string representation of the Document. :return: A string representation of the Document.

traverse(func: Callable[[Identified], None])

Enable a traversal of the entire object hierarchy contained in this document.

validate(report: ValidationReport = None) → ValidationReport

Validate all objects in this document.

validate_shacl(report: Optional[ValidationReport] = None) → ValidationReport

Validate this document using SHACL rules.

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.

write_string(file_format: str) → str
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.

Parameters

  • top_levels – Top Level objects to be copied

  • into_namespace – A namespace to be given to the new objects

  • into_document – A document to which the newly created objects will be added

Returns

A list of the newly created objects

data_path(path: str) → str

Expand path based on module installation directory.

Parameters

path –

Returns