Bases: object
Unique identifier of any resource so it can be referred to.
In QuakeML many elements and types can have a unique id that other elements use to refer to it. This is called a ResourceIdentifier and it is used for the same purpose in the obspy.core.event classes.
In QuakeML it has to be of the following regex form:
(smi|quakeml):[\w\d][\w\d\-\.\*\(\)_~']{2,}/[\w\d\-\.\*\(\)_~']
[\w\d\-\.\*\(\)\+\?_~'=,;#/&]*
e.g.
smi stands for “seismological meta-information”.
In this class it can be any hashable object, e.g. most immutable objects like numbers and strings.
Parameters: |
|
---|
General Usage
>>> res_id = ResourceIdentifier('2012-04-11--385392')
>>> res_id
ResourceIdentifier(resource_id="2012-04-11--385392")
>>> # If no resource_id is given it will be generated automatically.
>>> res_id
ResourceIdentifier(resource_id="...")
>>> # Supplying a prefix will simply prefix the automatically generated
>>> # resource_id.
>>> ResourceIdentifier(prefix='event')
ResourceIdentifier(resource_id="event/...")
ResourceIdentifiers can, and oftentimes should, carry a reference to the object they refer to. This is a weak reference which means that if the object get deleted or runs out of scope, e.g. gets garbage collected, the reference will cease to exist.
>>> event = Event()
>>> import sys
>>> ref_count = sys.getrefcount(event)
>>> res_id = ResourceIdentifier(referred_object=event)
>>> # The reference does not changed the reference count of the object.
>>> print ref_count == sys.getrefcount(event)
True
>>> # It actually is the same object.
>>> print event is res_id.getReferredObject()
True
>>> # Deleting it, or letting the garbage collector handle the object will
>>> # invalidate the reference.
>>> del event
>>> print res_id.getReferredObject()
None
The most powerful ability (and reason why one would want to use a resource identifier class in the first place) is that once a ResourceIdentifier with an attached referred object has been created, any other ResourceIdentifier instances with the same resource_id can retrieve that object. This works across all ResourceIdentifiers that have been instantiated within one Python run. This enables, e.g. the resource references between the different QuakeML elements to work in a rather natural way.
>>> event_object = Event()
>>> obj_id = id(event_object)
>>> res_id = "obspy.org/event/test"
>>> ref_a = ResourceIdentifier(res_id)
>>> # The object is refers to cannot be found yet. Because no instance that
>>> # an attached object has been created so far.
>>> print ref_a.getReferredObject()
None
>>> # This instance has an attached object.
>>> ref_b = ResourceIdentifier(res_id, referred_object=event_object)
>>> ref_c = ResourceIdentifier(res_id)
>>> # All ResourceIdentifiers will refer to the same object.
>>> assert(id(ref_a.getReferredObject()) == obj_id)
>>> assert(id(ref_b.getReferredObject()) == obj_id)
>>> assert(id(ref_c.getReferredObject()) == obj_id)
Any hashable type can be used as a resource_id.
>>> res_id = ResourceIdentifier((1,3))
>>> # Using a non-hashable resource_id will result in an error.
>>> res_id = ResourceIdentifier([1,2])
Traceback (most recent call last):
...
TypeError: resource_id needs to be a hashable type.
>>> res_id = ResourceIdentifier()
>>> res_id.resource_id = [1,2]
Traceback (most recent call last):
...
TypeError: resource_id needs to be a hashable type.
The id can be converted to a valid QuakeML ResourceIdentifier by calling the convertIDToQuakeMLURI() method. The resulting id will be of the form
smi:authority_id/prefix/resource_id
>>> res_id = ResourceIdentifier(prefix='origin')
>>> res_id.convertIDToQuakeMLURI(authority_id="obspy.org")
>>> res_id
ResourceIdentifier(resource_id="smi:obspy.org/origin/...")
>>> res_id = ResourceIdentifier('foo')
>>> res_id.convertIDToQuakeMLURI()
>>> res_id
ResourceIdentifier(resource_id="smi:local/foo")
>>> # A good way to create a QuakeML compatibly ResourceIdentifier from
>>> # scratch is
>>> res_id = ResourceIdentifier(prefix='pick')
>>> res_id.convertIDToQuakeMLURI(authority_id='obspy.org')
>>> res_id
ResourceIdentifier(resource_id="smi:obspy.org/pick/...")
>>> # If the given resource_id is already a valid QuakeML
>>> # ResourceIdentifier, nothing will happen.
>>> res_id = ResourceIdentifier('smi:test.org/subdir/id')
>>> res_id
ResourceIdentifier(resource_id="smi:test.org/subdir/id")
>>> res_id.convertIDToQuakeMLURI()
>>> res_id
ResourceIdentifier(resource_id="smi:test.org/subdir/id")
ResourceIdentifiers are considered identical if the resource_ids are the same.
>>> # Create two different resource_ids.
>>> res_id_1 = ResourceIdentifier()
>>> res_id_2 = ResourceIdentifier()
>>> assert(res_id_1 != res_id_2)
>>> # Equalize the resource_ids. NEVER do this. This just an example.
>>> res_id_2.resource_id = res_id_1.resource_id = 1
>>> assert(res_id_1 == res_id_2)
ResourceIdentifier instances can be used as dictionary keys.
>>> dictionary = {}
>>> res_id = ResourceIdentifier(resource_id="foo")
>>> dictionary[res_id] = "bar"
>>> # The same resource_id can still be used as a key.
>>> dictionary["foo"] = "bar"
>>> items = dictionary.items()
>>> items.sort()
>>> print items
[(ResourceIdentifier(resource_id="foo"), 'bar'), ('foo', 'bar')]
Attributes
__dict__ | |
__doc__ | str(object) -> string |
__module__ | str(object) -> string |
__weakref__ | list of weak references to the object (if defined) |
resource_id | unique identifier of the current instance |
Public Methods
convertIDToQuakeMLURI | Converts the current resource_id to a valid QuakeML URI. |
copy | Returns a copy of the ResourceIdentifier. |
getQuakeMLURI | Returns the resource_id as a valid QuakeML URI if possible. Does not |
getReferredObject | Returns the object associated with the resource identifier. |
setReferredObject | Sets the object the ResourceIdentifier refers to. |
Private Methods
_ResourceIdentifier__delResourceID | Deleting is forbidden and will not work. |
_ResourceIdentifier__getResourceID | |
_ResourceIdentifier__setResourceID |
Special Methods
__eq__ | |
__hash__ | Uses the same hash as the resource id. |
__init__ | |
__ne__ | |
__repr__ | |
__str__ |