def embed(self, rel, other, wrap=False):
"""Embeds a document inside this document.
Arguments:
- ``rel``: a string specifying the link relationship type of the
embedded resource. ``rel`` should be a well-known link relation name
from the IANA registry
(http://www.iana.org/assignments/link-relations/link-relations.xml),
a full URI, or a CURIE.
- ``other``: a ``Document`` instance that will be embedded in this
document. If ``other`` is identical to this document, this method
will silently fail.
- ``wrap``: Defaults to False, but if True, specifies that the embedded
resource object should be initally wrapped in a JSON array even if it
is the first embedded resource for the given ``rel``.
Calling code should use this method to add embedded resources instead
of modifying ``embedded`` directly.
This method embeds the given document in this document with the given
``rel``. If one or more documents have already been embedded for that
``rel``, the new document will be embedded in addition to those
documents.
"""
if other == self:
return
embedded = self.o.setdefault(EMBEDDED_KEY, {})
collected_embedded = CanonicalRels(embedded,
self.curies,
self.base_uri)
if rel not in collected_embedded:
if wrap:
embedded[rel] = [other.as_object()]
else:
embedded[rel] = other.as_object()
else:
original_rel = collected_embedded.original_key(rel)
current_embedded = embedded[original_rel]
if isinstance(current_embedded, list):
current_embedded.append(other.as_object())
else:
embedded[original_rel] = [current_embedded, other.as_object()]
if not self.draft.automatic_link:
return
url = other.url()
if not url:
return
if url in (link.url() for link in self.links.get(rel, [])):
return
self.add_link(rel, other, wrap=wrap)
def embed(self, rel, other, wrap=False):
"""Embeds a document inside this document.
Arguments:
- ``rel``: a string specifying the link relationship type of the
embedded resource. ``rel`` should be a well-known link relation name
from the IANA registry
(http://www.iana.org/assignments/link-relations/link-relations.xml),
a full URI, or a CURIE.
- ``other``: a ``Document`` instance that will be embedded in this
document. If ``other`` is identical to this document, this method
will silently fail.
- ``wrap``: Defaults to False, but if True, specifies that the embedded
resource object should be initally wrapped in a JSON array even if it
is the first embedded resource for the given ``rel``.
Calling code should use this method to add embedded resources instead
of modifying ``embedded`` directly.
This method embeds the given document in this document with the given
``rel``. If one or more documents have already been embedded for that
``rel``, the new document will be embedded in addition to those
documents.
"""
if other == self:
return
embedded = self.o.setdefault(EMBEDDED_KEY, {})
collected_embedded = CanonicalRels(embedded, self.curies,
self.base_uri)
if rel not in collected_embedded:
if wrap:
embedded[rel] = [other.as_object()]
else:
embedded[rel] = other.as_object()
else:
original_rel = collected_embedded.original_key(rel)
current_embedded = embedded[original_rel]
if isinstance(current_embedded, list):
current_embedded.append(other.as_object())
else:
embedded[original_rel] = [current_embedded, other.as_object()]
if not self.draft.automatic_link:
return
url = other.url()
if not url:
return
if url in (link.url() for link in self.links.get(rel, [])):
return
self.add_link(rel, other, wrap=wrap)
def url(self):
"""Returns the URL for the resource based on the ``self`` link.
This method returns the ``href`` of the document's ``self`` link if it
has one, or ``None`` if the document lacks a ``self`` link, or the
``href`` of the document's first ``self`` link if it has more than one.
"""
if not 'self' in self.links:
return None
self_link = self.links['self']
if isinstance(self_link, list):
for link in self_link:
return link.url()
return self_link.url()
def url(self):
"""Returns the URL for the resource based on the ``self`` link.
This method returns the ``href`` of the document's ``self`` link if it
has one, or ``None`` if the document lacks a ``self`` link, or the
``href`` of the document's first ``self`` link if it has more than one.
"""
if not 'self' in self.links:
return None
self_link = self.links['self']
if isinstance(self_link, list):
for link in self_link:
return link.url()
return self_link.url()
